Here’s your digest for today! #ariatosca undefined: sorry, i know this is taking forever :disappointed: but i honestly did not expect so much breakage. python is just too dynamic, and not enough library devs know how to play well with these dynamics to ensure proper OOP behavior. the good news is that we only ever have to solve all these problems once. undefined: Okay. Re service modifications models, definitely ignore them for now. undefined: [UPDATE]
Very happy to announce a PR for our code documentation. It is a huge PR in sheer number of lines... The resulting "User Manual for ARIA TOSCA" is thorough and enormous, and gives you a quick sense of just how big this project is. It starts with a section for the CLI (and eventually REST will be there), and then a deep dive into all our packages, modules, and APIs. I've divided the APIs into as many sections as make sense, though in some cases the pages are *very* big indeed. In those cases a added an extra "summary" at the top of the page that could make things easier. There's a lot crossreferencing, though there will obviously be a few bugs. (Please fix when you find them.) All the TOSCA references lead you directly to the place in the TOSCA specification. References to standard Python types will lead you to the Python 2.7 documentation. This is a good start, but we need some discipline in the team to keep this going. First off, there is a JIRA to add a tox test to make sure you do not break the documentation. But ... Sphinx errors only cover bad ReST, they won't catch sloppy formatting, and *don't* tell you if your crossreferences don't work. Also, Sphinx is only ... partially automated. There is manual work involved in adding new packages, modules, and sometimes even classes (you might need to update those summaries at top of pages). So, we're also going to have to get used to editing the rst files in the `docs/` dir. It's not a lot of work, but if you forget ... your new code might not be in the published documentation! Basically, as part of code reviews for PRs I think we should also review the *resulting* built documentation before merging. We could use readthedocs just for this purpose, as it has tools for building on branches. Of course we can also find a way to create our own hook. Very easy to build: `make docs` should do the trick. Finally, the wiki I posted a while ago is already out of date. I learned a lot and will need to change some of the rules there. So, don't refer to the wiki -- refer instead to other code documentation in the repo. #general #random
