Read the Docs Documentation

[pshriwise]

Description

This PR includes a documentation site overhaul using a read the docs theme. I've translated most of the exisiting content as a pure addition to the repository (for now) to support a content review before proceeding to cleanup the files and git history.

Highlights of this are:

• documentation versioning
• familiarity (it's become fairly standard in the OSS community I'd say)
• leveraging existing in-line documentation on the C++ API for DAGMC and UWUW

A rendered version of this draft content can be found here.

Motivation and Context

RTD is a well-known theme in the open-source community. The aim here is to provide familiarity as part of the new user experience with DAGMC

[gonuke]

Thanks @pshriwise - this looks mostly good. A few comments, probably only one or two really substantive ones - and we can decide to tackle these in subsequent PRs, perhaps, in order to move this forward.

[gonuke]

This seems light on front page content, even compared the relatively light current page? Is that intentional or expedient?

[pshriwise]

I've renamed/repurposed the "Is DAGMC for you?" section to an Introduction to DAGMC and made it more prominent on the main page. Does that read better?

[gonuke]

Should this be in the cubit_basics?

[shimwell]

resolved a simple conflict in the change log for the PR

[shimwell]

If I've understood everything correctly then I don't think this RTD theme supports multiple versions as it is. I think we currently have support for a single version. Hosting on readthedocs.io would be one option to allow muti version support.

It is still a nice improvement and I'm super keen on seeing this merged. It would be good to get these docs out for the current version. Before the next version release we could look into adding support for multiple versions.

I've just done some multi version docs for GEOUNED using the pydata theme and a couple of github actions to rebuild the docs and host it on gh-pages so perhaps some of the learning there can be useful.

I investigated 5 ways of adding versions to sphinx based docs and opted for pydata in the end.

1. https://github.com/Smile-SA/sphinx-versions no longer maintained does not work with latest sphinx
2. https://github.com/Holzhaus/sphinx-multiversion no longer maintained does not work with latest sphinx
3. https://www.codingwiththomas.com/blog/my-sphinx-best-practice-for-a-multiversion-documentation-in-different-languages nice approach, does not need extra packages but needs the most coding adding to local repo
4. https://pydata-sphinx-theme.readthedocs.io/en/stable/ looks like the best option, used by numpy and others
5. https://about.readthedocs.com (requires another login and admin accounts, includes adverts)

[pshriwise]

If I've understood everything correctly then I don't think this RTD theme supports multiple versions as it is. I think we currently have support for a single version. Hosting on readthedocs.io would be one option to allow muti version support.

It is still a nice improvement and I'm super keen on seeing this merged. It would be good to get these docs out for the current version. Before the next version release we could look into adding support for multiple versions.

I've just done some multi version docs for GEOUNED using the pydata theme and a couple of github actions to rebuild the docs and host it on gh-pages so perhaps some of the learning there can be useful.

I investigated 5 ways of adding versions to sphinx based docs and opted for pydata in the end.

1 https://github.com/Smile-SA/sphinx-versions no longer maintained does not work with latest sphinx
2 https://github.com/Holzhaus/sphinx-multiversion no longer maintained does not work with latest sphinx
3 https://www.codingwiththomas.com/blog/my-sphinx-best-practice-for-a-multiversion-documentation-in-different-languages nice approach, does not need extra packages but needs the most coding adding to local repo
4 https://pydata-sphinx-theme.readthedocs.io/en/stable/ looks like the best option, used by numpy and others
5 https://about.readthedocs.com (requires another login and admin accounts, includes adverts)

@shimwell true! It doesn't yet support multiple versions. I'm mainly focused on content here, and I agree it would be good to add before the next release. Thanks for the info on your experience supporting it for GEOUNED -- will likely save us some time. I'll let @gonuke comment as to hosting this on readthedocs vs. the UW site.

[gonuke]

We currently host on GH, not UW. I guess I don't have a strong feeling. It would be nice to move all Svalinn docs to the same place with the same theming

[shimwell]

I think hosting on github pages is a nice option as you can dive into the branch an make manual changes. If you are keen to stick with GH for the hosting then perhaps considering changing the theme from RTD to Pydata theme as this will make multi version docs easier in the future. If you want to stick with GH pages and stick with RTD theme then I think option 3 above is the only choice.