3 ms·
> No Python doc tool produces well-linked API docs out of the box. What's wrong with Sphinx-generated documentation? > I'd also like to see a local, easily in
by dozzie 10y ago
> No Python doc tool produces well-linked API docs out of the box.
What's wrong with Sphinx-generated documentation?
> I'd also like to see a local, easily installed tool that can generate documentation like this from just the source code of a project in one command. My previous efforts with Python doc tools had me downloading templates, writing a build pipeline that chained multiple tools together, etc.
Ever tried Sphinx? I never needed to download any templates or write
a pipeline to generate HTML (for man pages, Sphinx has some formatting off,
so I needed to adjust it).
Granted, it's a little different from JavaDoc-style tools, as you need to a)
mark all the functions and classes to see them documented, and b) provide
a skeleton for the pages layout, but this actually gives better control over
the resulting documentation and allows to include description of non-API
things, like architecture, examples, protocol specifications, or glossary.
- diafygi 10y agoI've tried probably half a dozen times to learn how to generate simple sphinx docs for my side projects. I start reading tutorials, then half a weekend goes by, and I give up because I'm knee deep in templates and rst. Either I'm reading the wrong tutorials or the learning curve for sphinx is much higher than you assume. Where are the tutorials that make it as simple as you say? All I want is something like: pip install sphinx sphinx autogen_html_docs --output /path/to/folder --input /path/to/mymodule_folder
- JelteF 10y agoSphinx really isn't that hard. The default config file is just quite crappy. Check out this one for one of my projects: https://github.com/JelteF/easyfuse/blob/master/docs/conf.py https://github.com/JelteF/easyfuse/blob/master/docs/conf.py Especially this line is quite important so you can put python references between backticks and they will automatically be interlinked: default_role = 'py:obj' This file is also quite useful: https://github.com/JelteF/easyfuse/blob/master/docs/create_doc_files.sh https://github.com/JelteF/easyfuse/blob/master/docs/create_d...
- pekk 10y agoSphinx's own documentation makes it vastly easier than `sphinx autogen_html_docs --output /path/to/folder --input /path/to/mymodule_folder` which reads like a really complicated command line of uncertain meaning.