search

svalinn / DAGMC

Direct Accelerated Geometry Monte Carlo Toolkit
https://svalinn.github.io/DAGMC
Other
96 stars 61 forks source link

Read the Docs Documentation #950

Open pshriwise opened 5 months ago

pshriwise commented 5 months ago

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:

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

shimwell commented 3 months ago

resolved a simple conflict in the change log for the PR

shimwell commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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.