Docs update with Zensical

[stuitje]

Description

This PR updates the MORS documentation significantly by introducing Zensical, thereby addressing FormingWorlds/PROTEUS#650. It also adds and updates a large number of pages:

• An updated homepage;
• A 'getting started' page with quicklinks;
• How-to guides and tutorial have updated formatting;
• Model overview in several pages;
• Explanation of coupling to PROTEUS;
• Parameter reference;
• API reference, a page for each module, using mkdocstrings;
• An updated contributing guide
• A proteus-framework page to introduce PROTEUS and link to its modules.

Updates also includes helper files, such as two css stylesheets (one for the proteus theme, one for footnotes) and an updated github workflow.

Verification

I have built the site locally using Chrome and Safari (I sadly don't have Firefox; but it has worked fine on Firefox for the other websites so far).

Relevant people

@timlichtenberg @nichollsh

[stuitje]

This is a great development and extremely useful, well done! I read through the docs pages and they are very clear and understandable. :)

A few suggestions to address before merge:

1. Missing trailing newline in src/mors/physicalmodel.py — the last line lacks a newline.
2. docs/assets/schematic_round.png is committed but unused. Explanations/proteus.md points at the remote raw.githubusercontent.com/... URL instead. Either switch the image src to the local path (offline-deterministic builds) or drop the local copy.
3. Silent stellar-mass clipping deserves a bigger shou-out. In Explanations/proteus.md, the line "if the configured mass falls outside the valid range, it is silently clipped" should be a !!! warning label; it's a numerical-correctness hazard for when people want to run PROTEUS runs around larger stars.
4. API page inconsistency: Reference/api/star.md is the only page that re-declares docstring_style: numpy. This this is redundant with the global setting in mkdocs.yml. Drop for consistency.
5. Tutorial unit has an ambiguity. Tutorials/first_run.md shows mors.Star(Mstar=1.0, Prot=2.7) without restating that the implicit reference age is AgeMinDefault = 1 Myr. One sentence can help clarify ambiguity what MORS then chooses for the age.
6. Can you call the "Tests for MORS" badge instead "MORS CI Test Suite"? This brings it in line with other new developments in the PROTEOS ecosystem.
7. Add a badge for the License of the code in the README and docs front page.
8. Add a How-to page on the Test suite of MORS. How is it organised, how to build tests? In Zalmoxis and Aragog I now split this apart even, to separate the mechanics from explanations on how to build/add tests.
9. I suggest to also rewrite the top-level README file from scratch to reflect the new structure. The README-level explanations are not needed anymore as they should be covered by the documentation.

The current test suite of MORS is not yet updated, as you did with e.g., Zalmoxis. I added a preliminary build_tests.md page adapted from your Zalmoxis test building page that already asks the developer to use the same markers (unit, smoke, integration, slow) and I added these markers to pyproject. However, in my run_tests.md testing guide, I should probably explain the current test suite, not the future one. What do you think?

I could also update the test suite soon :)

[timlichtenberg]

I agree that this is probably out of scope. Good for me to defer to a later action. :)

[stuitje]

I agree that this is probably out of scope. Good for me to defer to a later action. :)

I can make an issue about it:)
Today I will make a simple test-running how-to based on the current suite that can be updated later.

[nichollsh]

Sorry for the slow review on this, @stuitje, but thanks for making all these changes! Overall the docs look great and I have been able to follow all of the instructions/steps successfully on my laptop. In particular, I appreciate all your efforts to expand the tutorials and clarify the phrasing throughout. Very cool.

A few minor things...

1. I get this warning when importing mors. Maybe worth fixing.

../../miniforge3/envs/proteus/lib/python3.12/site-packages/requests/__init__.py:113
  /home/harrison/miniforge3/envs/proteus/lib/python3.12/site-packages/requests/__init__.py:113: RequestsDependencyWarning: urllib3 (2.6.3) or chardet (7.4.3)/charset_normalizer (3.4.4) doesn't match a supported version!
    warnings.warn(

2. Tim's point about stellar mass clipping is important, but at the moment it is relegated to deep within the docs. People might miss this, and think their model is doing something different. Would it be possible to add a non-spammy warning into the code, somewhere, about this? Maybe when the tracks are loaded.

3. What's up with the comment about not publishing one of the pages? It says "This page is not yet online and should be updated based on the new MORS test suite. Do not yet publish this page!"

4. Can the README_OLD.md file be removed?

5. Please add yourself and @timlichtenberg to the list of authors in pyproject.toml

[timlichtenberg]

From my perspective can go ahead; once you address Harrison's points let's go. Re: 5 from Harrison: didn't we say no authors/developers anywhere? So my suggestion is to get rid of this entirely and let the contributors pane speak for itself. Good for you @nichollsh?

[stuitje]

Sorry for the slow review on this, @stuitje, but thanks for making all these changes! Overall the docs look great and I have been able to follow all of the instructions/steps successfully on my laptop. In particular, I appreciate all your efforts to expand the tutorials and clarify the phrasing throughout. Very cool.

A few minor things...

1. I get this warning when importing mors. Maybe worth fixing.

../../miniforge3/envs/proteus/lib/python3.12/site-packages/requests/__init__.py:113
  /home/harrison/miniforge3/envs/proteus/lib/python3.12/site-packages/requests/__init__.py:113: RequestsDependencyWarning: urllib3 (2.6.3) or chardet (7.4.3)/charset_normalizer (3.4.4) doesn't match a supported version!
    warnings.warn(

2. Tim's point about stellar mass clipping is important, but at the moment it is relegated to deep within the docs. People might miss this, and think their model is doing something different. Would it be possible to add a non-spammy warning into the code, somewhere, about this? Maybe when the tracks are loaded.
3. What's up with the comment about not publishing one of the pages? It says "This page is not yet online and should be updated based on the new MORS test suite. Do not yet publish this page!"
4. Can the README_OLD.md file be removed?
5. Please add yourself and @timlichtenberg to the list of authors in pyproject.toml

Thanks Harrison, not slow at all.
About point 3: I have now removed the build_tests.md page, as it was still a draft based on the test-building page for Zalmoxis, which I haven't published to the docs yet because the test suite hasn't been updated. I now have it locally and can adjust + publish it later.
About point 4: I don't mind removing it. I thought it could stay for reference, but it is also in the commit history of course.
Point 1,2: will take a look, thanks! I think I can add a warning in the code.
Point 5; don't mind adding myself; the author list in pyproject.toml is also still there in proteus, do we want to remove all of them? I thought the discussion was more about removing them from the docs; but I am fine with removing them from every repo. @timlichtenberg

[nichollsh]

Re: 5 from Harrison: didn't we say no authors/developers anywhere?

This is different to the documentation. I believe that the author list in the pyproject.toml file is mandatory as part of the Python package schema.

[stuitje]

Sorry for the slow review on this, @stuitje, but thanks for making all these changes! Overall the docs look great and I have been able to follow all of the instructions/steps successfully on my laptop. In particular, I appreciate all your efforts to expand the tutorials and clarify the phrasing throughout. Very cool.

A few minor things...

1. I get this warning when importing mors. Maybe worth fixing.

../../miniforge3/envs/proteus/lib/python3.12/site-packages/requests/__init__.py:113
  /home/harrison/miniforge3/envs/proteus/lib/python3.12/site-packages/requests/__init__.py:113: RequestsDependencyWarning: urllib3 (2.6.3) or chardet (7.4.3)/charset_normalizer (3.4.4) doesn't match a supported version!
    warnings.warn(

2. Tim's point about stellar mass clipping is important, but at the moment it is relegated to deep within the docs. People might miss this, and think their model is doing something different. Would it be possible to add a non-spammy warning into the code, somewhere, about this? Maybe when the tracks are loaded.
3. What's up with the comment about not publishing one of the pages? It says "This page is not yet online and should be updated based on the new MORS test suite. Do not yet publish this page!"
4. Can the README_OLD.md file be removed?
5. Please add yourself and @timlichtenberg to the list of authors in pyproject.toml

I addressed points 3-5.

About point 2: since the mass clipping is done in proteus (in the star wrapper), I think that's where a warning should go. I can add it in my next proteus PR, would that work?

About point 1: I don't get this warning in both my proteus and mors environments. Is it possible that updating those packages in your environment fixes it?

[nichollsh]

New changes are good with me. Thanks for updating the author list and removing the old files. It's good that you caught this logger-name issue too.

Indeed, this warning does seem to be caused by my Python environment more generally, and not by this PR, so we can not worry about this.

Including the other warning about stellar mass clipping in PROTEUS itself probably does make more sense, since that's where it's done. We should make sure not to forget about adding that.

Happy for this to be merged. Thanks again, @stuitje!