Merge pull request #2770 from stfc/2543_refresh_getting_going

(towards #2543) Simplify Introduction documentation
stfc · Nov 14, 2024 · 9f4890a · 9f4890a
2 parents 8336dd6 + eb1b96d
commit 9f4890a
Show file tree

Hide file tree

Showing 71 changed files with 241 additions and 952 deletions.
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -52,7 +52,7 @@ on:
   workflow_dispatch:
 
 jobs:
-  sphinx-link-check:
+  build-documentation:
     if: ${{ github.repository != 'stfc/PSyclone-mirror' }}
     # Check all Sphinx documentation for dead links.
     runs-on: ubuntu-latest
@@ -66,11 +66,18 @@ jobs:
     - run: sudo apt-get install -y graphviz doxygen
     - run: python -m pip install --upgrade pip
     - run: pip install .[doc]
+    # First we need to build the docs and launch a server, otherwise the
+    # intershpinx links would be broken
     - run: cd doc/user_guide; make html
     - run: cd doc/developer_guide; make html
     - run: cd doc/reference_guide; make html
     - run: cd doc/psyad/user_guide; make html
     - run: cd doc; python -m http.server &
+    # Now we can check for warnings and broken links
+    - run: cd doc/user_guide; make html SPHINXOPTS="-W --keep-going"
+    - run: cd doc/developer_guide; make html SPHINXOPTS="-W --keep-going"
+    # TODO #1280: - run: cd doc/reference_guide; make html SPHINXOPTS="-W --keep-going"
+    - run: cd doc/psyad/user_guide; make html SPHINXOPTS="-W --keep-going"
     - run: cd doc/user_guide; make linkcheck
     - run: cd doc/developer_guide; make linkcheck
     - run: cd doc/reference_guide; make linkcheck

diff --git a/changelog b/changelog
@@ -277,6 +277,8 @@
 
 	105) PR #2745 for #2661. Add support for kernels that operate on halos.
 
+	106) PR #2770 towards #2543. Improve UG introduction.
+
 release 2.5.0 14th of February 2024
 
 	1) PR #2199 for #2189. Fix bugs with missing maps in enter data

diff --git a/doc/developer_guide/developers_gocean1p0_stencils.rst b/doc/developer_guide/developers_gocean1p0_stencils.rst
diff --git a/doc/user_guide/conf.py b/doc/user_guide/conf.py
@@ -39,7 +39,9 @@
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
               'sphinx.ext.intersphinx', 'sphinx.ext.coverage',
               'sphinx.ext.imgmath', 'sphinx.ext.viewcode',
-              'sphinxcontrib.bibtex', 'apilinks']
+              'sphinxcontrib.bibtex', 'sphinx_tabs.tabs',
+              'apilinks',
+              ]
 bibtex_bibfiles = ['../bibliography/references.bib']
 
 # GITHUB_PR_NUMBER is set in .github/workflows/python-package.yml when