From fa336bdab3c604a42ea1b7f7396c986f9ba67f9c Mon Sep 17 00:00:00 2001 From: Matthew Hambley Date: Thu, 4 Apr 2024 14:49:29 +0100 Subject: [PATCH 1/6] Migrated to PyData Sphinx theme and fixed API generation. --- docs/source/_templates/crown-copyright.html | 11 +++++ docs/source/api.rst | 10 +++++ docs/source/conf.py | 50 +++++++++++---------- docs/source/index.rst | 2 +- pyproject.toml | 2 +- 5 files changed, 49 insertions(+), 26 deletions(-) create mode 100644 docs/source/_templates/crown-copyright.html create mode 100644 docs/source/api.rst diff --git a/docs/source/_templates/crown-copyright.html b/docs/source/_templates/crown-copyright.html new file mode 100644 index 00000000..44657219 --- /dev/null +++ b/docs/source/_templates/crown-copyright.html @@ -0,0 +1,11 @@ +{# Crown copyright is displayed differently to normal. #} +{# Configured from conf.py as per usual. #} +{% if show_copyright and copyright %} +

+ {% if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {% else %} + {% trans copyright=copyright|e %}© Crown Copyright {{ copyright }}.{% endtrans %} + {% endif %} +

+{% endif %} diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 00000000..6a5a1bbd --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,10 @@ +API Documentation +================= + +This API documentation is generated from comments within the source code. + +.. autosummary:: + :toctree: api + :recursive: + + fab diff --git a/docs/source/conf.py b/docs/source/conf.py index 68762f24..d036262f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -17,8 +17,8 @@ # -- Project information ----------------------------------------------------- -project = 'fab' -copyright = '2023' +project = 'Fab' +copyright = '2024 Met Office. All rights reserved.' author = 'Fab Team' # The full version, including alpha/beta/rc tags @@ -52,24 +52,35 @@ exclude_patterns = [] -# -- Options for HTML output ------------------------------------------------- +# -- Autodoc ----------------------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# +autodoc_default_options = { + 'members': True, + 'show-inheritane': True +} -# ugly -# html_theme = "classic" +autoclass_content = 'both' -# poor contrast between title, h1 & h2 -# html_theme = "sphinxdoc" -# html_theme = "sphinx_rtd_theme" -# html_theme = 'python_docs_theme' -# good contrast between title, h1 & h2 -# html_theme = 'alabaster' -html_theme = 'sphinx_material' +# -- Options for HTML output ------------------------------------------------- +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'pydata_sphinx_theme' + +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/metomi/fab", + "icon": "fa-brands fa-github" + } + ], + "footer_start": ["crown-copyright"], + "footer_center": ["sphinx-version"], + "footer_end": ["theme-version"], +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -93,12 +104,3 @@ # include default values in argument descriptions typehints_defaults = 'braces-after' - -# needed when using material theme -html_sidebars = { - "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"] -} -# needed when not using material theme -# html_sidebars = { -# "**": ["globaltoc.html", "searchbox.html"] -# } diff --git a/docs/source/index.rst b/docs/source/index.rst index 0b5458c7..fc03936e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -81,7 +81,7 @@ See also writing_config advanced_config features - Api Reference + Api Reference development glossary genindex diff --git a/pyproject.toml b/pyproject.toml index 9e242d43..2a932e9d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,7 +23,7 @@ c-language = ['python-clang'] plots = ['matplotlib'] tests = ['pytest', 'pytest-cov', 'pytest-mock'] checks = ['flake8', 'mypy'] -docs = ['sphinx', 'sphinx-material', 'sphinx-autodoc-typehints', 'sphinx-copybutton'] +docs = ['sphinx', 'pydata-sphinx-theme>=0.15.2', 'sphinx-autodoc-typehints', 'sphinx-copybutton'] dev = ['sci-fab[plots, tests, checks, docs]'] [project.scripts] From e22f4693225b7a23ace0067325c207f2307d8be0 Mon Sep 17 00:00:00 2001 From: Matthew Hambley Date: Thu, 4 Apr 2024 15:12:00 +0100 Subject: [PATCH 2/6] Downgrade theme version to one which is available. --- pyproject.toml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 2a932e9d..87f0d8d0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,7 +23,10 @@ c-language = ['python-clang'] plots = ['matplotlib'] tests = ['pytest', 'pytest-cov', 'pytest-mock'] checks = ['flake8', 'mypy'] -docs = ['sphinx', 'pydata-sphinx-theme>=0.15.2', 'sphinx-autodoc-typehints', 'sphinx-copybutton'] +docs = ['sphinx', + 'pydata-sphinx-theme>=0.13.3', + 'sphinx-autodoc-typehints', + 'sphinx-copybutton'] dev = ['sci-fab[plots, tests, checks, docs]'] [project.scripts] From adfa6d9fcd94dd818527ea2c68ad241efbfea2b6 Mon Sep 17 00:00:00 2001 From: Matthew Hambley Date: Thu, 4 Apr 2024 15:32:22 +0100 Subject: [PATCH 3/6] Bump depricated actions in workflow. --- .github/workflows/build.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index ded9d856..936c7bd9 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -12,9 +12,9 @@ jobs: python-version: ['3.7', '3.8', '3.9', '3.10'] steps: - - uses: actions/checkout@v1 + - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v1 + uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - name: Setup Compiler From d7ee3c92960990cb7f47ba6b58b60ba19136de34 Mon Sep 17 00:00:00 2001 From: Matthew Hambley Date: Thu, 4 Apr 2024 15:38:02 +0100 Subject: [PATCH 4/6] Prefer a more modern flake8. --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 87f0d8d0..07547477 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,7 +22,7 @@ classifiers = [ c-language = ['python-clang'] plots = ['matplotlib'] tests = ['pytest', 'pytest-cov', 'pytest-mock'] -checks = ['flake8', 'mypy'] +checks = ['flake8>=7.0.0', 'mypy'] docs = ['sphinx', 'pydata-sphinx-theme>=0.13.3', 'sphinx-autodoc-typehints', From 25196f37af02c4219eaf2b39336a79228aa58b9d Mon Sep 17 00:00:00 2001 From: Matthew Hambley Date: Thu, 4 Apr 2024 15:51:36 +0100 Subject: [PATCH 5/6] Downgrade flake8 to pre v7.0.0. --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 07547477..cb694cf7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,7 +22,7 @@ classifiers = [ c-language = ['python-clang'] plots = ['matplotlib'] tests = ['pytest', 'pytest-cov', 'pytest-mock'] -checks = ['flake8>=7.0.0', 'mypy'] +checks = ['flake8>=6.1.0', 'mypy'] docs = ['sphinx', 'pydata-sphinx-theme>=0.13.3', 'sphinx-autodoc-typehints', From 4c1b35d22d6e969308d662d80ed361447eae5422 Mon Sep 17 00:00:00 2001 From: Matthew Hambley Date: Thu, 4 Apr 2024 15:54:23 +0100 Subject: [PATCH 6/6] Another go at guessing the correct flake8 version. --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index cb694cf7..76424ead 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,7 +22,7 @@ classifiers = [ c-language = ['python-clang'] plots = ['matplotlib'] tests = ['pytest', 'pytest-cov', 'pytest-mock'] -checks = ['flake8>=6.1.0', 'mypy'] +checks = ['flake8>=5.0.4', 'mypy'] docs = ['sphinx', 'pydata-sphinx-theme>=0.13.3', 'sphinx-autodoc-typehints',