Allow easy readthedocs integration
xiki-tempula opened this issue · 7 comments
readthedocs allows free hosting of the doc and is using sphinx as the backend. I think it will be very helpful if relevant yaml files could be setup by the cookie cutter.
I was working on this a while ago (#93 ). I can try returning to it soon to see if what I had in this PR can be brought up to date.
As a quick note I have switch to MkDocs Material + Netlify these days. No ads and I find it a bit easier experience since its pure Markdown + pure JAMStack without the majority of Sphinx's idiosyncrasies.
Worth noting there is also a Sphinx Material if you like the look.
Excellent to know! I am getting my PR on RTD up to date, but I imagine this might warrant some discussion on what to include. Material looks like a very nice Sphinx theme. I imagine this could also be used with RTD. So MkDocs is another documentation tool besides Sphinx?
We could give people the choice of docs tools (MkDocs or Sphinx), but this would (I imagine) require someone to develop the MkDocs files. We could also give a choice on Sphinx theme (Material vs RTD), or even change the default theme of the cookie cutter. Many choices!
I'm finishing up the PR for supporting RTD hosting with Sphinx, just in case we want to support that for now.
@Lnaden , thoughts?
As a quick note I have switch to MkDocs Material + Netlify these days.
Aha, I've been wondering what pydantic was using.
Sphinx RTD is a good default, its likely the most widely used in the CMS space and while finicky- resources on how to work around Sphinx/RTD issues are well known. MkDocs Material is newer (as seen by the syntax and code style), but also means the module ecosystem and support network are less robust. I'm not sure I suggest supporting too many options here, but I hope worth being aware of!
As a quick note I have switch to MkDocs Material + Netlify these days.
Aha, I've been wondering what pydantic was using.
I also think Pydantic's auto doc generation is 🔥. Automatically builds the example here from a python file without comments.
The encode/pydantic/FastAPI/etc way of doing things is worth drawing from.