4 ms·

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.

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 11y ago
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 11y ago
  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.
bpicolo 11y ago
I don't think it does provide any new tools? (None that I noticed). That said, I use sphinx a lot. I think it's a totally fine tool
mplewis 11y ago
Continuous documentation is continuous because you just edit your docstrings, push to GitHub, and your docs are now updated.
- mpdehaan2 11y ago
  Got it -- more of a README/ HOWTO than a project/application. Thanks!
agj 11y ago
Sphinx, or rather Docutils, does eat Markdown now: https://github.com/rtfd/recommonmark https://github.com/rtfd/recommonmark There is no access to Sphinx's directives/extensions, as it implements Commonmark support, which doesn't yet offer an extension syntax as part of the spec. Once it does, writing in Markdown will me more useful, but currently it's limited to basic markup and naive linking.

illumen 11y ago

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 11y ago
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.

bpicolo 11y ago

I don't think it does provide any new tools? (None that I noticed). That said, I use sphinx a lot. I think it's a totally fine tool

mplewis 11y ago

Continuous documentation is continuous because you just edit your docstrings, push to GitHub, and your docs are now updated.

mpdehaan2 11y ago
Got it -- more of a README/ HOWTO than a project/application. Thanks!

agj 11y ago

Sphinx, or rather Docutils, does eat Markdown now: https://github.com/rtfd/recommonmark https://github.com/rtfd/recommonmark There is no access to Sphinx's directives/extensions, as it implements Commonmark support, which doesn't yet offer an extension syntax as part of the spec. Once it does, writing in Markdown will me more useful, but currently it's limited to basic markup and naive linking.