search

MolSSI / cookiecutter-cms

Python-centric Cookiecutter for Molecular Computational Chemistry Packages
MIT License
385 stars 89 forks source link

Allow easy readthedocs integration #114

Closed xiki-tempula closed 3 years ago

xiki-tempula commented 4 years ago

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.

janash commented 4 years ago

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.

dgasmith commented 3 years ago

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.

janash commented 3 years ago

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?

loriab commented 3 years ago

As a quick note I have switch to MkDocs Material + Netlify these days.

Aha, I've been wondering what pydantic was using.

dgasmith commented 3 years ago

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!

dgasmith commented 3 years ago

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.

janash commented 3 years ago

Closed by #115 . This PR added a RTD yaml and a conda environment yaml in the docs folder.