3 ms·
Basic markdown and Sphinx to build into HTML, publishing via github pages. It's an open source project so putting the docs alongside the code just makes sense.
by stichers 5y ago
Basic markdown and Sphinx to build into HTML, publishing via github pages. It's an open source project so putting the docs alongside the code just makes sense. Although Sphinx isn't great for my money, it gets the job done.
- acidburnNSA 5y agoI have grown to absolutely love Sphinx. The plugins are wonderful, including Sphinx gallery, jupyter integration, and Sphinx-needs for requirements management.
- stichers 5y agoI think it grows on you. There's a way to work with it and if you settle on that, it makes it easier than fighting against the prevailing tide. I find I spend a lot of time looking up opaque build errors but that is partly because the contributing authors aren't all that familiar with it, so their markdown is less than 'pure'
- byteface 5y agoI also use sphinx and https://readthedocs.org/ https://readthedocs.org/. lots of sphinx repos are open source so you can use them for inspiration... https://www.sphinx-doc.org/en/master/examples.html https://www.sphinx-doc.org/en/master/examples.html
- ak217 5y agoI use this combination too, and I love it. Sphinx has great hackability and support, while github pages is free and very reliable. Here is a script that I use to publish to github pages, assuming the sphinx config is under "docs": sphinx-build docs docs/html git branch -D gh-pages || true git checkout -B gh-pages-stage touch docs/html/.nojekyll git add --force docs/html git commit -m "Docs" git push --force origin $(git subtree split --prefix docs/html --branch gh-pages):refs/heads/gh-pages git checkout -