Convert most of project to mystmd

updates

.github/workflows/web_documentation.yml

@@ -40,7 +40,8 @@ jobs:
                                  sphinx-book-theme \
                                  sphinx-toolbox \
                                  sphinx-copybutton \
-                                 pyshtools
+                                 myst-parser \
+                                 pyshtools \
 
     - name: Build ctplanet using pip
       shell: bash -l {0}
@@ -54,34 +55,8 @@ jobs:
         cd docs
         make html
 
-    - name: Upload artifact of the html output
-      uses: actions/upload-artifact@v4
+    - name: Deploy
+      if: github.event_name != 'pull_request'
+      uses: JamesIves/github-pages-deploy-action@v4
       with:
-        name: gh-pages-documentation
-        path: docs/_build/html/
-        retention-days: 1
-
-    - name: Clean gh-pages branch
-      shell: bash -l {0}
-      run: |
-        git switch gh-pages
-        git clean -fd
-        git config --local user.email "[email protected]"
-        git config --local user.name "GitHub Action"
-
-    - name: Download artifact
-      uses: actions/download-artifact@v4
-      with:
-        name: gh-pages-documentation
-
-    - name: Commit changes
-      shell: bash -l {0}
-      run: |
-        git add .
-        git commit -m "Update gh-pages documenation" -a || true
-
-    - name: Push changes
-      uses: ad-m/github-push-action@master
-      with:
-        branch: gh-pages
-        github_token: ${{ secrets.GITHUB_TOKEN }}
+        folder: docs/_build/html

docs/_static/custom.css

@@ -0,0 +1,6 @@
+span.project-version {
+  color: #999999;
+  font-size: 0.8em;
+  font-weight: 600;
+  margin-left: 0px;
+}

docs/conf.py

@@ -1,29 +1,35 @@
 import datetime
 import ctplanet
+from packaging.version import Version
 
 # Project information
 year = datetime.date.today().year
 project = 'ctplanet'
-copyright = "{}, The ctplanet developers".format(year)
+copyright = "{}".format(year)
 author = 'the ctplanet developers'
-version = ctplanet.__version__.split(sep='-')[0]  # use version of last tag
-release = version
+version = Version(ctplanet.__version__).base_version
 
 # General configuration
-extensions = ['sphinx_copybutton',
-              'sphinx.ext.autodoc',
-              'sphinx.ext.autosummary',
-              'sphinx.ext.mathjax',
-              'sphinx.ext.napoleon',
-              'sphinx_toolbox.collapse',
-          ]
+extensions = [
+    'sphinx_copybutton',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinx_toolbox.collapse',
+    'myst_parser',
+]
+myst_enable_extensions = [
+    'attrs_block',
+    'colon_fence',
+]
 
 # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
 autosummary_generate = True
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
 
 # Options for HTML output
 html_theme = 'sphinx_book_theme'
@@ -37,6 +43,10 @@
     "use_source_button": False,
     "use_issues_button": False,
     "use_download_button": False,
+    "logo": {
+        "text": f'<span class="project-version">{version}</span>'
+    },
+    "home_page_in_toc": False,
 }
 html_static_path = ['_static']
 html_show_sourcelink = False
@@ -45,6 +55,5 @@
 html_title = "ctplanet"
 html_short_title = "ctplanet"
 html_last_updated_fmt = "%b %d, %Y"
-
-html_context = {
-}
+html_css_files = ["custom.css"]
+html_context = {}

docs/examples.rst → docs/examples.md

@@ -1,95 +1,102 @@
-Examples
-========
+# Examples
 
-.. note::
-    In order to access the example files, it is necessary to download or clone the `ctplanet` repo from `GitHub <https://github.com/MarkWieczorek/ctplanet>`_. The files are located in the `examples` directory.
+:::{note}
+In order to access the example files, it is necessary to download or clone the [ctplanet repo](https://github.com/MarkWieczorek/ctplanet) from GitHub. The files are located in the `examples` directory.
+:::
 
-Moon
-----
+## Moon
 
-.. collapse:: <b>Moon-Crust.py</b>
-
-    .. literalinclude:: ../examples/Moon-Crust.py
+````{collapse} <b>Moon-Crust.py</b>
+```{literalinclude} ../examples/Moon-Crust.py
+```
+````
 
 A script that demonstrates how to calculate the thickness of the lunar crust
 using either a constant or variable density crust. The latter can be used
 to reproduce the results presented in *Wieczorek et al.* (2013).
 
-.. collapse:: <b>Moon-Core.py</b>
-
-    .. literalinclude:: ../examples/Moon-Core.py
+````{collapse} <b>Moon-Core.py</b>
+```{literalinclude} ../examples/Moon-Core.py
+```
+````
 
 Calculate the hydrostatic relief of the lunar core accounting for the
 non-hydrostatic potential that comes from the lithosphere.
 
-Mars
-----
-
-.. collapse:: <b>Mars-Crust.py</b>
+## Mars
 
-    .. literalinclude:: ../examples/Mars-Crust.py
+````{collapse} <b>Mars-Crust.py</b>
+```{literalinclude} ../examples/Mars-Crust.py
+```
+````
 
 A script that demonstrates how to calculate the thickness of the Martian
 crust using either a constant or variable density crust. For the variable
 density crust, the density is assumed to change discontinuously across the
 dichotomy boundary.
 
-.. collapse:: <b>Mars-Crust-hydrostatic-tests.py</b>
-
-    .. literalinclude:: ../examples/Mars-Crust-hydrostatic-tests.py
+````{collapse} <b>Mars-Crust-hydrostatic-tests.py</b>
+```{literalinclude} ../examples/Mars-Crust-hydrostatic-tests.py
+```
+````
 
 Create a crustal thickness map of Mars from gravity and topography and
 compare how results change if hydrostatic interfaces are not taken into
 account.
 
-.. collapse:: <b>Mars-Crust-InSight.py</b>
-
-    .. literalinclude:: ../examples/Mars-Crust-InSight.py
+````{collapse} <b>Mars-Crust-InSight.py</b>
+```{literalinclude} ../examples/Mars-Crust-InSight.py
+```
+````
 
 Create a crustal thickness map of Mars from gravity and topography, using
 the InSight crustal thickness constraint.
 
-.. collapse:: <b>Mars-Crust-InSight-dichotomy.py</b>
-
-    .. literalinclude:: ../examples/Mars-Crust-InSight-dichotomy.py
+````{collapse} <b>Mars-Crust-InSight-dichotomy.py</b>
+```{literalinclude} ../examples/Mars-Crust-InSight-dichotomy.py
+```
+````
 
 Create a crustal thickness map of Mars from gravity and topography, using
 the InSight crustal thickness constraint and different densities across
 the dichotomy boundary.
 
-.. collapse:: <b>Mars-fcn.py</b>
-
-    .. literalinclude:: ../examples/Mars-fcn.py
+````{collapse} <b>Mars-fcn.py</b>
+```{literalinclude} ../examples/Mars-fcn.py
+```
+````
 
 Compute the free core nutation period of Mars.
 
-.. collapse:: <b>Mars-shape.py</b>
-
-    .. literalinclude:: ../examples/Mars-shape.py
+````{collapse} <b>Mars-shape.py</b>
+```{literalinclude} ../examples/Mars-shape.py
+```
+````
 
 Create images related to Mars in *Wieczorek et al.* (2019).
 
-.. collapse:: <b>Mars-j2.py</b>
-
-    .. literalinclude:: ../examples/Mars-j2.py
+````{collapse} <b>Mars-j2.py</b>
+```{literalinclude} ../examples/Mars-j2.py
+```
+````
 
 Compute the contribution to the gravitational J2 of Mars from hydrostatic
 interfaces beneath the lithosphere.
 
-Earth
------
+## Earth
 
-.. collapse:: <b>Earth-shape.py</b>
-
-    .. literalinclude:: ../examples/Earth-shape.py
+````{collapse} <b>Earth-shape.py</b>
+```{literalinclude} ../examples/Earth-shape.py
+```
+````
 
 Compute hydrostatic relief of Earth using PREM.
 
-Ceres
------
-
-.. collapse:: <b>Ceres-shape.py</b>
+## Ceres
 
-    .. literalinclude:: ../examples/Ceres-shape.py
+````{collapse} <b>Ceres-shape.py</b>
+```{literalinclude} ../examples/Ceres-shape.py
+```
+````
 
 Calculate the hydrostatic shape of Ceres.

docs/index.rst → docs/index.md

@@ -1,22 +1,22 @@
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: Getting Started
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Getting Started
 
-   installation.rst
-   examples.rst
-   references.rst
+installation.md
+examples.md
+references.md
+```
 
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: Reference Documentation
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: Reference Documentation
 
-   source/api.rst
+source/api.rst
+```
 
-
-CTPLANET
-========
+# CTPLANET
 
 **ctplanet** provides several functions for working with the gravitational field of planetary crusts and hydrostatic density interfaces in the mantle and core. With this python package, you can:
 

docs/installation.md

@@ -0,0 +1,68 @@
+# Installation
+
+## Dependencies
+
+The `ctplanet` package requires `pyshtools` (>=4.13.1), which can be installed using either `conda`
+
+```
+conda install -c conda-forge pyshtools
+```
+
+or `pip`
+
+```
+pip install pyshtools
+```
+
+## Install using pip
+
+Install the `ctplanet` module using pip
+
+```
+pip install ctplanet
+```
+
+## Install from source
+
+First, clone the repo on your computer and cd to the new directory
+
+```
+git clone https://github.com/MarkWieczorek/ctplanet.git
+cd ctplanet
+```
+
+To install `ctplanet` in the active Python environment lib folder, use
+
+```
+pip install .
+```
+
+To instead install the files in the current working directory and link them to the system Python directory, use
+
+```
+pip install -e .
+```
+
+The second method is preferred if you plan on modifying the `ctplanet` source code.
+
+## Working with the example scripts
+
+To access the example scripts, you must download the `ctplanet`
+repository from GitHub. The easiest way to do this is by cloning the repo
+
+```
+git clone https://github.com/MarkWieczorek/ctplanet.git
+```
+
+To execute a script, it is only necessary to enter the `examples` directory and run the file using the python command
+
+```
+cd ctplanet/examples
+python Moon-Crust.py
+```
+
+:::{note}
+Depending on how your system is set up, it might be necessary to use
+explicitly ``python3`` and ``pip3`` instead of ``python`` and ``pip`` in
+the above commands.
+:::