

Python Continuous Documentation - icgood
https://github.com/icgood/continuous-docs/

======
mpdehaan2
I'm not sure what this project does rather than advocate use of Sphinx and
provide some tools to set it up, that is, what is continuous about it, I don't
know. Perhaps something to work on in the README.

All being said, Sphinx is a decent tool (and I wrote WAAY too much of it in
the last three years), but I have grown to strongly dislike reStructured Text
-- I have to look up the URL linking syntax, for instance, almost every time I
use it.

Having something like Sphinx that ate Markdown instead would make me rather
happy.

~~~
illumen
Having a cheat sheet around, or editor support helps.

I'm not sure fragmenting doc string syntax further is a good idea for the
python community. There's been efforts to support Markdown on pypi for
README.md. But even that has been met with a lot of resistance.

~~~
zo1
I really don't understand this. Everyone wants to do it their way when it
comes to docstrings. One of the big unfortunate culprits is "PyDev", which is
an Eclipse plugin for python development. It's sole developer decided to
divert from the already-established (if not already-hacky) docstring format of
type hinting for lists. So now, instead of: "list of str", we have to contend
with another format of: "list(str)".

I can't wait for the python PEP standards for function-annotation to become
standard and permeate the editors.

------
goblin89
Great initiative, but beware relying on automatically generated documentation.
Keep units documented in the code, and have your higher-level docs handwritten
and hand-structured elsewhere, is the policy I’ve arrived at lately.

(It doesn’t make sense to spend resources on having units documented
separately from code, because you don’t need such docs unless you’re working
with code. Loads of auto-generated docs also gives a false impression of your
project being properly documented, which it isn’t unless you also have higher-
level hand-written documentation somewhere.

Similarly, it doesn’t make sense to keep high-level architecture docs in
docstrings, as it’s not tied to specific modules, and you normally need it
when you’re thinking big picture as opposed to working with specific code
units.)

Overall, kudos—good documentation is important.

If you’re concerned about writing good documentation, I recommend reading
these series by Jacob Kaplan-Moss (of Django core development team):
[https://jacobian.org/writing/great-
documentation/](https://jacobian.org/writing/great-documentation/)

------
agj
It's worth mentioning the besides the steps for requirements installation,
this workflow isn't limited to Python. Sphinx has support for writing
referential documentation with many other languages. Integrating with per-
language tools to provide automatically generated reference docs is something
we're starting to build out more with [https://github.com/rtfd/sphinx-
autoapi](https://github.com/rtfd/sphinx-autoapi), though it's still in its
early stages.

