Nexus: New documentation theme and structure

[brockdyer03]

Proposed changes

1. Switch from ReadTheDocs theme to the PyData Sphinx Theme (the one NumPy uses)
2. Add a logo
3. Generate API documentation
4. Restructure file layout

This PR requires #5961 and #5977.

Closes #2716.

What type(s) of changes does this code introduce?

• Documentation

Does this introduce a breaking change?

• No

What systems has this change been tested on?

Desktop, Fedora Linux 43 (KDE Plasma Desktop Edition)
AMD Ryzen 9 7900X (12 cores, 24 logical processors)

Python        3.14.4
uv            0.11.3
cif2cell      2.1.0
coverage      7.13.5
h5py          3.16.0
matplotlib    3.10.9
numpy         2.4.4
pycifrw       4.4.6
pydot         4.0.1
pytest        9.0.3
pytest-cov    7.1.0
pytest-order  1.4.0
scipy         1.17.1
seekpath      2.2.1
spglib        2.7.0
sphinx        9.1.0

Checklist

• • I have read the pull request guidance and develop docs
• • This PR is up to date with the current state of 'develop'

[brockdyer03]

This is the artifact from the build: https://nexus-workflows--5978.org.readthedocs.build/en/5978/

[prckent]

Block until after next release.

Also, as previously communicated, and while the enthusiasm is acknowledged, we will work with a professional designer on any new logo.

[kayahans]

Dear all, Brock wanted me to share our communication over Teams as feedback on the manual. I hope it is useful:

1. When you click "Nexus Documentation" on the left top, it opens the table of contents. I think it would be better to have table of contents on the left sidebar and then have some text on the main window (you could copy paste overview of Nexus section here). In this way when you click homepage, then it would say what Nexus is about. That page could also list which codes it can interface. It could get more attention of the new users that way.

2. I think API section could use more formatting. When I compared Structure and QMCPACK modules, I didn't see a uniform formatting across these sections. For example structure section has subsections like "list of module contents" and "module contents" under QMCPACK modules it starts as 2.2.1 QMCPACK Input. I think it could benefit from a way to organize them in a uniform way.

3. In the API sections there are some functions such as is_int(), is_float() (https://nexus-workflows--5978.org.readthedocs.build/en/5978/api_docs/qmcpack/index.html). Could these functions be inherited from parent classes? Maybe you have a better idea on this, but it could be better to skip those for the interest of making the documentation more concise and maybe highlight the inheritance structure?
   For example in https://nexus-workflows--5978.org.readthedocs.build/en/5978/api_docs/espresso/main.html#nexus.pwscf.Pwscf
   There are a list of Methods, which I believe should come from Simulation class. For Pwscf class, I would only document if a method is overriden or new. Maybe that is what you already did, I don't know. You already highlight Bases:simulation here, but Simulation is not clickable yet.

4. In the sections, say for QMCPACK, there is section 2.2 QMCPACK Modules and then subsections 2.2.1 QMCPACK Input 2.2.2 QMCPACK etc. I think these are referring to qmcpack_input.py and qmcpack.py. When there is another layer of labeling as 2.2.1 QMCPACK then it feels a bit confusing to me. I rather have it named 2.2.1 qmcpack.py . Every code that interfaces with nexus has to have minimum of 3 files (input, sim, analyzer). Some codes have more than one analyzer and there is convention issues for example pyscf_sim.py (there is no pyscf.py in nexus for good reasons) vs qmcpack.py (why not qmcpack_sim.py), so maybe that is difficult to enforce.

5. Section 2.2.4 looks like a material that could go into user guide or tutorials, I would think that API reference should only explain what the code is.

6. When I click Section 2.3 on the left sidebar, then I get this: https://nexus-workflows--5978.org.readthedocs.build/en/5978/api_docs/espresso/index.html
   it says that
   The Quantum ESPRESSO utilities are split across 9 modules:
   pwscf_analyzer.py
   pwscf_data_reader.py
   pwscf_input.py
   pwscf_postprocessors.py
   pwscf.py
   It looks like there is a 1-1 match with for example "quantum espresso input" and pwscf_input.py file. However pwscf_input.py file above is not clickable (maybe not yet). I think a page like section 2.3 would be better if it could list capabilities rather than having a long list of methods. You can see that list once you click 2.3.1 for example, it feels like duplicating information to have it in 2.3 as well. I think it would be nice if new users could easily see capabilities (for example it works with QE 6.x and 7.0.x using such and such calculations Hubbard, NEB etc.) it would be better as a documentation. This kind of info may also be in the user manual as a new page as capabilities.

7. Code blocks in user guide could have easy copy buttons.

[brockdyer03]

To respond to some of your comments @kayahans:

3. In the API sections there are some functions such as is_int(), is_float() (https://nexus-workflows--5978.org.readthedocs.build/en/5978/api_docs/qmcpack/index.html). Could these functions be inherited from parent classes? Maybe you have a better idea on this, but it could be better to skip those for the interest of making the documentation more concise and maybe highlight the inheritance structure?
   For example in https://nexus-workflows--5978.org.readthedocs.build/en/5978/api_docs/espresso/main.html#nexus.pwscf.Pwscf
   There are a list of Methods, which I believe should come from Simulation class. For Pwscf class, I would only document if a method is overriden or new. Maybe that is what you already did, I don't know. You already highlight Bases:simulation here, but Simulation is not clickable yet.

This is actually two separate comments. First is the documentation of functions like is_int() and is_float(), which are generally not supposed to be user-facing and should either go at the end of their respective pages, or somehow be grouped together and labeled as developer-only. I'm open to opinions on that.

The other comment about inheritance is a good one. To get hyperlinks properly working I have to go in and declare all of the correct crossref aliases through numpydoc, which may be a rather significant task, possibly for a future PR.

4. In the sections, say for QMCPACK, there is section 2.2 QMCPACK Modules and then subsections 2.2.1 QMCPACK Input 2.2.2 QMCPACK etc. I think these are referring to qmcpack_input.py and qmcpack.py. When there is another layer of labeling as 2.2.1 QMCPACK then it feels a bit confusing to me. I rather have it named 2.2.1 qmcpack.py . Every code that interfaces with nexus has to have minimum of 3 files (input, sim, analyzer). Some codes have more than one analyzer and there is convention issues for example pyscf_sim.py (there is no pyscf.py in nexus for good reasons) vs qmcpack.py (why not qmcpack_sim.py), so maybe that is difficult to enforce.

This is indeed an artifact of there being a variable number of submodules that contribute to one goal. I figured putting all of the qmcpack_<thing>_analyzer.py modules into one "QMCPACK Analyzers" section would be best, since they all are essentially doing the same thing. It does also mean that I don't need to worry about stuff like pyscf_sim.py versus a pyscf.py, which could be confusing.

There is an additional challenge w.r.t. sections that are labeled 2.2.x in QMCPACK Input, since currently the docstring for QmcpackInput.modify() uses a different sort of reStructuredText header delimiter than the ones that are recognized by numpydoc. I have opened a PR in numpydoc that should in theory make it so we don't need to worry about this, but until that is merged it will remain a bit sketchy around there.

5. Section 2.2.4 looks like a material that could go into user guide or tutorials, I would think that API reference should only explain what the code is.

Agreed. I believe all of the text in there is really just for User Guide stuff, but it also is like the Examples section in numpydoc, so I put it in there for now. This is subject for debate.

6. When I click Section 2.3 on the left sidebar, then I get this: https://nexus-workflows--5978.org.readthedocs.build/en/5978/api_docs/espresso/index.html
   it says that
   The Quantum ESPRESSO utilities are split across 9 modules:
   pwscf_analyzer.py
   pwscf_data_reader.py
   pwscf_input.py
   pwscf_postprocessors.py
   pwscf.py
   It looks like there is a 1-1 match with for example "quantum espresso input" and pwscf_input.py file. However pwscf_input.py file above is not clickable (maybe not yet). I think a page like section 2.3 would be better if it could list capabilities rather than having a long list of methods. You can see that list once you click 2.3.1 for example, it feels like duplicating information to have it in 2.3 as well. I think it would be nice if new users could easily see capabilities (for example it works with QE 6.x and 7.0.x using such and such calculations Hubbard, NEB etc.) it would be better as a documentation. This kind of info may also be in the user manual as a new page as capabilities.

Two notes. One, it accidentally does say 9 modules instead of 5 because I forgot to change it when I copy+pasted that section over from the QMCPACK part. Oops.

Second, I could definitely rework those sections to behave more as user-facing documentation than API documentation, and then make the modules themselves clickable so that you can get the in-depth API docs only if the reader is really interested.

7. Code blocks in user guide could have easy copy buttons.

Good point. I'll add sphinx-copybutton as a dependency for that :)

[brockdyer03]

Lots of work got done in these commits. I've changed a few things around, made sure to address comments 1(ish), 2, 4, and 7 from @kayahans.

Still more work and discussion needed to finalize the rest.

[prckent]

Please can you fix the build?

  File "/home/docs/checkouts/readthedocs.org/user_builds/nexus-workflows/envs/5978/lib/python3.13/site-packages/sphinx/cmd/build.py", line 493, in main
    return build_main(argv)
  Void error:
    item CifFile is from unavailable module CifFile  
    this python module must be installed on your system to use this feature
  exiting.

Unfortunately there is now some CifFile contamination. This should be removed since we can not require these kinds of optional Nexus dependencies to build the documentation. The documentation should be buildable without optional dependencies. I suggest verifying that the documentation builds in a minimal python environment.

[brockdyer03]

Please can you fix the build?

  File "/home/docs/checkouts/readthedocs.org/user_builds/nexus-workflows/envs/5978/lib/python3.13/site-packages/sphinx/cmd/build.py", line 493, in main
    return build_main(argv)
  Void error:
    item CifFile is from unavailable module CifFile  
    this python module must be installed on your system to use this feature
  exiting.

Unfortunately there is now some CifFile contamination. This should be removed since we can not require these kinds of optional Nexus dependencies to build the documentation. The documentation should be buildable without optional dependencies. I suggest verifying that the documentation builds in a minimal python environment.

There's something wrong somewhere else. Even if I have pycifrw installed I can't build the docs.

[brockdyer03]

Looks like a strange bug caused the autodoc Sphinx extension to not be able to import CifFile from CifFile (which really is just PyCifRW). Importing it in the conf.py file seems to have fixed that, though I can't even begin to imagine why.