Here’s your digest for today! #ariatosca undefined: Re: docs, Tal are you adding this to our new Jekyll site? <@U53P75YTD> ^^ undefined: <@U53NR8XFF> teach me how? undefined: <@U5416JV9R> i will wrap up the documentation work today. in a way it is open ended and seems like i can go on forever improving, but actually our goals now are just to get everything to work consistently, and i'm nearly done. along the way i am hitting some "low-hanging fruit" that's easy to fix, but i'm *not* going through and documenting everything properly at this point. undefined: yup :thumbsup: undefined: ran: hm, perhaps i didn't see that code. if it works, we don't have to do that. but we still need to see about metadata undefined: [UPDATE] unfortunately not done yet with documentation. there continue to be sticky issues. good news is that i found a workaround for the sphinx annoyance with automatically trying to cross reference types. i posted the fix to the github issue: <https://github.com/sphinx-doc/sphinx/issues/3866>.
the main problem is how to properly document our modules. my solution so far has been to use `:ivar:` (many people suggest this), but it's actually wrong. these are properties that are documented separately, so it causes duplication in the final docs. also, we've been having serious problems with people on the team not updating these -- and i don't blame them, because they are separate from the main docs. i'm trying to find a way to solve this elegantly... i have a good idea (i think) but it will be more work. sphinx is ... difficult. please be patient, in the end we will have really high quality documentation. <@U53NR8XFF> on second thought i think it will be better to post our documentation on <http://readthedocs.org|readthedocs.org>. it's a very standard place for python packages, and it has a convenient hook that will regenerate our documentation and post it on every commit to master. on our web site we can just link to that. undefined: I would rather not have the docs external
