From 891ff9d99718bbc567b438fd610d23515bde52ac Mon Sep 17 00:00:00 2001 From: Leonardo Uieda Date: Wed, 7 Feb 2024 17:40:02 -0300 Subject: [PATCH] Update documentation dependencies (#53) Use the latest sphinx, theme, and plugins. Had to make some adjustments for things to work with the recent versions. In particular, replacing sphinx-panels with sphinx-design. --- .github/workflows/docs.yml | 18 +--- .gitignore | 1 + doc/Makefile | 1 + doc/conf.py | 13 +-- doc/gallery_src/alps-gps-velocity.py | 6 +- doc/gallery_src/britain-magnetic.py | 2 +- doc/gallery_src/british-columbia-lidar.py | 2 +- doc/gallery_src/bushveld-gravity.py | 2 +- doc/gallery_src/caribbean-bathymetry.py | 2 +- doc/gallery_src/osborne-magnetic.py | 2 +- doc/gallery_src/sierra-negra-topography.py | 2 +- doc/gallery_src/southern-africa-gravity.py | 2 +- doc/index.rst | 101 +++++++++++---------- env/requirements-docs.txt | 14 +-- environment.yml | 16 ++-- 15 files changed, 87 insertions(+), 97 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6cc3a3e..b419a25 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -33,7 +33,7 @@ jobs: runs-on: ubuntu-latest env: REQUIREMENTS: env/requirements-docs.txt env/requirements-build.txt - PYTHON: 3.9 + PYTHON: "3.10" steps: # Cancel any previous run of the test job @@ -62,14 +62,10 @@ jobs: run: git fetch origin 'refs/tags/*:refs/tags/*' - name: Setup Miniconda - uses: conda-incubator/setup-miniconda@v2 + uses: conda-incubator/setup-miniconda@v3 with: python-version: ${{ env.PYTHON }} - miniforge-variant: Mambaforge - use-mamba: true channels: conda-forge,defaults - # Needed for caching - use-only-tar-bz2: true - name: Collect requirements run: | @@ -89,17 +85,11 @@ jobs: echo "Collected dependencies:" cat requirements-full.txt - - name: Setup caching for conda packages - uses: actions/cache@v3 - with: - path: ~/conda_pkgs_dir - key: conda-${{ runner.os }}-${{ env.PYTHON }}-${{ hashFiles('requirements-full.txt') }} - - name: Install requirements - run: mamba install --quiet --file requirements-full.txt python==$PYTHON + run: conda install --quiet --file requirements-full.txt python==$PYTHON - name: List installed packages - run: mamba list + run: conda list - name: Build source and wheel distributions run: | diff --git a/.gitignore b/.gitignore index 584573d..c498d53 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,4 @@ MANIFEST .coverage.* *.ipynb **/_version_generated.py +doc/sg_execution_times.rst diff --git a/doc/Makefile b/doc/Makefile index 15b5cd2..c4c5b81 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -25,6 +25,7 @@ clean: rm -rf $(BUILDDIR)/doctrees rm -rf $(BUILDDIR)/linkcheck rm -rf api/generated + rm -rf gallery rm -rf .ipynb_checkpoints clean-all: clean diff --git a/doc/conf.py b/doc/conf.py index 1b13e9b..1de5b6d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -33,25 +33,18 @@ "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinx.ext.napoleon", - "sphinx_panels", + "sphinx_design", "sphinx_gallery.gen_gallery", "jupyter_sphinx", ] -# Disable including boostrap CSS for sphinx_panels since it's already included -# with sphinx-book-theme -panels_add_bootstrap_css = False -panels_css_variables = { - "tabs-color-label-inactive": "hsla(231, 99%, 66%, 0.5)", -} - # Configuration to include links to other project docs when referencing # functions/classes intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), "numpy": ("https://numpy.org/doc/stable/", None), "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), - "xarray": ("https://xarray.pydata.org/en/stable/", None), + "xarray": ("https://docs.xarray.dev/en/stable/", None), "pooch": ("https://www.fatiando.org/pooch/latest/", None), "pygmt": ("https://www.pygmt.org/latest/", None), } @@ -103,7 +96,7 @@ # ----------------------------------------------------------------------------- html_title = f'{project} {version}' html_short_title = project -html_logo = "_static/ensaio-logo.png" +# html_logo = "_static/ensaio-logo.png" html_favicon = "_static/favicon.png" html_last_updated_fmt = "%b %d, %Y" html_copy_source = True diff --git a/doc/gallery_src/alps-gps-velocity.py b/doc/gallery_src/alps-gps-velocity.py index 2f850de..d82b06b 100644 --- a/doc/gallery_src/alps-gps-velocity.py +++ b/doc/gallery_src/alps-gps-velocity.py @@ -67,7 +67,7 @@ y=data.latitude, direction=[angle, length * scale_factor], style="v0.15c+e", - color="blue", + fill="blue", pen="1p,blue", ) # Plot a quiver caption @@ -76,7 +76,7 @@ y=42, direction=[[0], [1 * scale_factor]], style="v0.15c+e", - color="blue", + fill="blue", pen="1p,blue", ) fig.text( @@ -96,7 +96,7 @@ fig.plot( x=data.longitude, y=data.latitude, - color=data.velocity_up_mmyr, + fill=data.velocity_up_mmyr, style="c0.2c", cmap=True, pen="0.5p,black", diff --git a/doc/gallery_src/britain-magnetic.py b/doc/gallery_src/britain-magnetic.py index f957bf1..b24f4f6 100644 --- a/doc/gallery_src/britain-magnetic.py +++ b/doc/gallery_src/britain-magnetic.py @@ -52,7 +52,7 @@ x=data.longitude, y=data.latitude, style="c0.02c", - color=data.total_field_anomaly_nt, + fill=data.total_field_anomaly_nt, cmap=True, projection="M15c", ) diff --git a/doc/gallery_src/british-columbia-lidar.py b/doc/gallery_src/british-columbia-lidar.py index e79c989..e86c13c 100644 --- a/doc/gallery_src/british-columbia-lidar.py +++ b/doc/gallery_src/british-columbia-lidar.py @@ -51,7 +51,7 @@ ) pygmt.makecpt(cmap="viridis", series=[data.elevation_m.min(), data.elevation_m.max()]) fig.plot( - x=data.longitude, y=data.latitude, color=data.elevation_m, cmap=True, style="c0.05c" + x=data.longitude, y=data.latitude, fill=data.elevation_m, cmap=True, style="c0.05c" ) fig.colorbar(frame='af+l"elevation [m]"') fig.show() diff --git a/doc/gallery_src/bushveld-gravity.py b/doc/gallery_src/bushveld-gravity.py index 6f950ec..88d7b7a 100644 --- a/doc/gallery_src/bushveld-gravity.py +++ b/doc/gallery_src/bushveld-gravity.py @@ -64,7 +64,7 @@ fig.plot( x=data.longitude, y=data.latitude, - color=data.gravity_disturbance_mgal, + fill=data.gravity_disturbance_mgal, cmap=True, style="c0.1c", ) diff --git a/doc/gallery_src/caribbean-bathymetry.py b/doc/gallery_src/caribbean-bathymetry.py index 44d5cd9..e5c8c29 100644 --- a/doc/gallery_src/caribbean-bathymetry.py +++ b/doc/gallery_src/caribbean-bathymetry.py @@ -51,7 +51,7 @@ ) pygmt.makecpt(cmap="viridis", series=[data.depth_m.min(), data.depth_m.max()]) fig.plot( - x=data.longitude, y=data.latitude, color=data.depth_m, cmap=True, style="c0.02c" + x=data.longitude, y=data.latitude, fill=data.depth_m, cmap=True, style="c0.02c" ) fig.colorbar(frame='af+l"bathymetric depth [m]"') fig.coast(land="#666666") diff --git a/doc/gallery_src/osborne-magnetic.py b/doc/gallery_src/osborne-magnetic.py index d66be20..b51607b 100644 --- a/doc/gallery_src/osborne-magnetic.py +++ b/doc/gallery_src/osborne-magnetic.py @@ -56,7 +56,7 @@ fig.plot( x=data.longitude, y=data.latitude, - color=data.total_field_anomaly_nt, + fill=data.total_field_anomaly_nt, style="c0.075c", cmap=True, ) diff --git a/doc/gallery_src/sierra-negra-topography.py b/doc/gallery_src/sierra-negra-topography.py index 7d47bd4..912a9e2 100644 --- a/doc/gallery_src/sierra-negra-topography.py +++ b/doc/gallery_src/sierra-negra-topography.py @@ -52,7 +52,7 @@ ) pygmt.makecpt(cmap="viridis", series=[data.elevation_m.min(), data.elevation_m.max()]) fig.plot( - x=data.longitude, y=data.latitude, color=data.elevation_m, cmap=True, style="c0.01c" + x=data.longitude, y=data.latitude, fill=data.elevation_m, cmap=True, style="c0.01c" ) fig.colorbar(frame='af+l"elevation [m]"') fig.show() diff --git a/doc/gallery_src/southern-africa-gravity.py b/doc/gallery_src/southern-africa-gravity.py index 542cbce..619592b 100644 --- a/doc/gallery_src/southern-africa-gravity.py +++ b/doc/gallery_src/southern-africa-gravity.py @@ -54,7 +54,7 @@ fig.plot( x=data.longitude, y=data.latitude, - color=data.gravity_mgal, + fill=data.gravity_mgal, cmap=True, style="c0.05c", ) diff --git a/doc/index.rst b/doc/index.rst index 4b7b979..ede6ba1 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,13 +2,9 @@ .. raw:: html -

- Ensaio -

- -.. raw:: html - -

+ +

Ensaio

+

Practice datasets to probe your code

A sampling of our datasets @@ -24,55 +20,67 @@ caching the data on your computer. This means that datasets are only downloaded if they can't be found on your computer already. -.. panels:: - :header: text-center text-large - :card: border-1 m-1 text-center +.. grid:: 1 2 1 2 + :margin: 5 5 0 0 + :padding: 0 0 0 0 + :gutter: 4 - **Getting started** - ^^^^^^^^^^^^^^^^^^^ + .. grid-item-card:: :octicon:`info` Getting started + :text-align: center + :class-title: sd-fs-5 + :class-card: sd-p-3 - New to Ensaio? Start here! + New to Ensaio? Start here! - .. link-button:: using - :type: ref - :text: Downloading data - :classes: btn-outline-primary btn-block stretched-link + .. button-ref:: using + :ref-type: ref + :click-parent: + :color: primary + :outline: + :expand: - --- + .. grid-item-card:: :octicon:`paintbrush` Browse our datasets + :text-align: center + :class-title: sd-fs-5 + :class-card: sd-p-3 - **Need help?** - ^^^^^^^^^^^^^^ + Take a look at what's available - Ask on our community channels + .. button-ref:: gallery + :ref-type: ref + :color: primary + :outline: + :expand: - .. link-button:: https://www.fatiando.org/contact - :type: url - :text: Join the conversation - :classes: btn-outline-primary btn-block stretched-link + .. grid-item-card:: :octicon:`comment-discussion` Need help? + :text-align: center + :class-title: sd-fs-5 + :class-card: sd-p-3 - --- + Ask on our community channels. - **Browse our datasets** - ^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. button-link:: https://www.fatiando.org/contact + :click-parent: + :color: primary + :outline: + :expand: - Take a look at what's available + Join the conversation :octicon:`link-external` - .. link-button:: gallery - :type: ref - :text: Gallery - :classes: btn-outline-primary btn-block stretched-link + .. grid-item-card:: :octicon:`file-badge` Reference documentation + :text-align: center + :class-title: sd-fs-5 + :class-card: sd-p-3 - --- + A list of modules and functions. - **Reference documentation** - ^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. button-ref:: api + :ref-type: ref + :color: primary + :outline: + :expand: - A list of modules and functions - - .. link-button:: api - :type: ref - :text: API reference - :classes: btn-outline-primary btn-block stretched-link +---- .. seealso:: @@ -80,14 +88,9 @@ computer already. `Fatiando a Terra `_ project. ----- - - -Table of contents ------------------ - .. toctree:: :caption: User Guide + :hidden: :maxdepth: 1 install.rst @@ -97,6 +100,7 @@ Table of contents .. toctree:: :caption: Reference + :hidden: :maxdepth: 1 api/index.rst @@ -106,6 +110,7 @@ Table of contents .. toctree:: :caption: Community + :hidden: Join the community Code of Conduct diff --git a/env/requirements-docs.txt b/env/requirements-docs.txt index 13b45c4..db78715 100644 --- a/env/requirements-docs.txt +++ b/env/requirements-docs.txt @@ -1,12 +1,12 @@ -sphinx==4.3.* -sphinx-book-theme==0.1.* -sphinx-gallery==0.10.* -sphinx-panels==0.6.* -jupyter-sphinx==0.3.* +sphinx==7.2.* +sphinx-book-theme==1.1.* +sphinx-gallery==0.15.* +sphinx-design==0.5.* +jupyter-sphinx==0.5.* numpy pandas xarray netcdf4 -pygmt==0.5.0 -gmt==6.2.0 +pygmt==0.11.0 +gmt==6.5.0 ipython diff --git a/environment.yml b/environment.yml index df92c30..4c4ed39 100644 --- a/environment.yml +++ b/environment.yml @@ -3,7 +3,7 @@ channels: - conda-forge - defaults dependencies: - - python==3.9 + - python==3.10 - pip - make # Run @@ -16,17 +16,17 @@ dependencies: - pytest-cov - coverage # Documentation - - sphinx==4.3.* - - sphinx-book-theme==0.1.* - - sphinx-gallery==0.10.* - - sphinx-panels==0.6.* - - jupyter-sphinx==0.3.* + - sphinx==7.2.* + - sphinx-book-theme==1.1.* + - sphinx-gallery==0.15.* + - sphinx-design==0.5.* + - jupyter-sphinx==0.5.* - numpy - pandas - xarray - netcdf4 - - pygmt==0.5.0 - - gmt==6.2.0 + - pygmt==0.11.0 + - gmt==6.5.0 - ipython # Style - black