[stichers]

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.

[byteface]

I also use sphinx and 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

[ak217]

I 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 -

[acidburnNSA]

I have grown to absolutely love Sphinx. The plugins are wonderful, including Sphinx gallery, jupyter integration, and Sphinx-needs for requirements management.

[stichers]

I 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'