Create a proper documentation site

[empicano]

I'd like to move the documentation from the README to a separate documentation site. In terms of tooling, I quite like the look of the attrs documentation. It's built with Sphinx and the Furo Theme.

I'm not a real fan of reStructuredText over Markdown (or the multitude of alternatives like MyST or Djot -- markup languages are a nice little rabbit hole to dive into😄), but it's the standard for Python, so I'd roll with it.

What do you think?

[frederikaalund]

I think it's a good idea to move the documentation into a dedicated site. 👍

Personally, I also prefer Markdown over reStructuredText but the latter is indeed more standard in the Python world.
Admittedly, I don't have a lot of experience in this field (documentation frameworks) so I'm not a good reference on that point.

In any case, I like this initiative and I fully support it. 😄

[empicano]

By the way. I used some Sphinx extensions in our setup now, namely sphinx-copybutton, sphinx-autobuild, and MyST.

MyST is a Markdown flavor that (supposedly) lets us do anything that's possible with reST, but in Markdown. 👍

[JonathanPlasse]

There is also MkDocs. FastAPI uses it. The code examples are in separate files, and they are tested and then embedded in the documentation.
I do not know if it is possible to do the same with Sphinx.

[empicano]

That's a good point, and I'd like to set up automatic testing for our examples as well. I didn't try it, but it should be possible:

• https://www.sphinx-doc.org/en/master/tutorial/describing-code.html#including-doctests-in-your-documentation
• https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html

[JonathanPlasse]

This discussion could be interesting encode/httpx#1220

[empicano]

That's a great find, there are a lot of good points in there 👍

From the discussion I see the maintainers are leaning towards a switch to Sphinx, they even migrated the httpcore docs to Sphinx. That somehow petered out though. For httpcore there are both Sphinx and MkDocs documentation sites, and the other encode projects didn't switch (yet?) either.

I'll try out Sphinx, and see how it goes. The only real criticism of Sphinx I found in the discussion (apart from favoritism of Markdown vs. reST) is that the setup is more complicated, but then that's extra work only for me 😄 Other than that Sphinx seems to be a lot more feature-rich.