Docs update

.github/CODEOWNERS

@@ -1,5 +1,5 @@
-# Set Ivar Stefansson and Eirik Keilegavlen as global owners
-* @keileg @IvarStefansson
+# Set Ivar Stefansson, Omar Duran, and Eirik Keilegavlen as global owners
+* @keileg @IvarStefansson @OmarDuran
 
 # Make vlipovac code owner of the docs folder
-docs/* @vlipovac
+/docs/* @vlipovac

.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
     # https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#specifying-a-python-version
     strategy:
       matrix:
-        python-version:  ["3.8", "3.9", "3.10"]  # TODO: Change 3.10.6 to 3.10 when mypy error is fixed
+        python-version:  ["3.8", "3.9", "3.10"]
       # Complete all versions in matrix even if one fails.
       fail-fast: false
 
@@ -53,9 +53,8 @@ jobs:
         # Cache the full python environment, this is more efficient than just caching pip
         # https://blog.allenai.org/python-caching-in-github-actions-e9452698e98d
         path: ${{ env.pythonLocation }}
-        key: ${{ env.pythonLocation }}-pip-${{ hashFiles('**/requirements-dev.txt') }}
-        restore-keys: |
-          ${{ runner.os }}-pip-
+        # Hash both ordinary requirements and those specific for developmnet.
+        key: ${{ env.pythonLocation }}-${{ hashFiles('setup.py') }}-${{ hashFiles('**/requirements.txt', '**/requirements-dev.txt') }}
 
     - name: Cache mypy
       uses: actions/cache@v3
@@ -66,7 +65,10 @@ jobs:
 
     - name: Install external libraries
       run: |
-        sudo apt-get install libglu1-mesa libgeos-dev
+        # Various packages that must be installed 
+        # Install libffi v7. This was (seemed to be) necessary in Nov 2022. The reason could be that
+        # ubuntu-latest was updated, libffi was removed, and scipy complained.
+        sudo apt-get install libglu1-mesa libgeos-dev libffi7
         export LD_LIBRARY_PATH=/usr/local/lib64/:$LD_LIBRARY_PATH
 
     - name: Install requirements
@@ -97,14 +99,14 @@ jobs:
       if: ${{ always() }}
       run: flake8 src 
 
-    - name: mypy
-      if: ${{ always() }}
-      run: mypy src --cache-dir mypy-cache-${{ matrix.python-version}}
-
     - name: unit tests
       if: ${{always()}}
       run: pytest tests/unit
 
+    - name: mypy
+      if: ${{ always() }}
+      run: mypy src --cache-dir mypy-cache-${{ matrix.python-version}}
+
     - name: integration tests
       if: ${{always()}}
       run: pytest tests/integration

docs/conf.py

@@ -40,9 +40,10 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.napoleon',
     'sphinx.ext.autodoc',
+    # 'sphinx_autodoc_typehints',  # this moves type links from signature to docstring
     'sphinx.ext.intersphinx',
-    'sphinx.ext.napoleon',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
 ]
@@ -62,28 +63,38 @@
 # -- Options for HTML output ------------------------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages. Currently set to theme of Python 2 docs
-html_theme = "nature"
+html_theme = "sphinx_rtd_theme"
 
 # 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,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["static"]
-
-# Customize the html theme here. Supported  customization depends on the chosen HTML theme,
-# but unknown entries will cause no error when compiling.
-html_theme_options = {
-    # "rightsidebar": "false",
-    # "relbarbgcolor": "black",
-    # "externalrefs": "true",
-    # "bodyfont": "Arial",
-    # "headfont": "Arial",
-}
+html_static_path = []
 
 html_short_title = "PorePy"
 html_split_index = True
 html_copy_source = False
 html_show_sourcelink = False
 html_show_sphinx = False
+html_baseurl = 'https://pmgbergen.github.io/porepy/'
+
+# relative path to project logo, to be displayed on docs webpage
+# html_logo = ''
+
+# theme-specific customization, read the docs of respective theme
+html_theme_options = {
+    'logo_only': False,
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+    'style_external_links': True,
+    'vcs_pageview_mode': '',
+    'style_nav_header_background': '#2980B9',
+    # Toc options
+    'collapse_navigation': False,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False
+}
 
 # -- Autodoc Settings -------------------------------------------------------------------------
 
@@ -96,9 +107,21 @@
 # orders the members of an object group wise, e.g. private, special or public methods
 autodoc_member_order = "groupwise"  # alphabetical-groupwise-bysource
 
+# Avoid double appearance of documentation if child member has no docs
+autodoc_inherit_docstrings = False
+
+# do not evaluate default arguments, leave as is
+autodoc_preserve_defaults = True
+
 # type hints will be shortened: porepy.grids.grid.Grid -> Grid
 autodoc_typehints_format = "short"
 
+# uses type hints in signatures for e.g. linking (default)
+autodoc_typehints = "signature"
+
+# display types in signature which are documented, or all (by default)
+autodoc_typehints_description_target = 'all'  # all-documented
+
 # default configurations for all autodoc directives
 autodoc_default_options = {
     "members": True,
@@ -109,14 +132,15 @@
     "no-value": False
 }
 
-# uses type hints in signatures for e.g. linking (default)
-autodoc_typehints = "signature"
-
-# Avoid double appearance of documentation if child member has no docs
-autodoc_inherit_docstrings = False
-
 # Used to shorten the parsing of type hint aliases
-autodoc_type_aliases = {}
+# NOTE: As of now, hyperlinking to type aliases is an open issue
+# see https://github.com/sphinx-doc/sphinx/issues/10785
+autodoc_type_aliases = {
+    'ArrayLike': 'ArrayLike',
+    'NDArray': 'NDArray',
+    'DTypeLike': 'DTypeLike',
+    'ExampleArrayLike': 'ExampleArrayLike',
+}
 
 # -- Napoleon Settings ------------------------------------------------------------------------
 
@@ -125,16 +149,27 @@
 # napoleon_include_init_with_doc = False
 # napoleon_include_private_with_doc = False
 # napoleon_include_special_with_doc = False
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = True
 napoleon_use_ivar = False
 napoleon_use_param = True
+napoleon_use_keyword = True
 napoleon_use_rtype = True
-napoleon_preprocess_types = False
-napoleon_type_aliases = None
+napoleon_preprocess_types = True
+napoleon_type_aliases = {
+}
 napoleon_attr_annotations = True
 
+# -- Autodoc typehints settings ---------------------------------------------------------------
+
+# typehints_fully_qualified = False
+# always_document_param_types = False
+# typehints_document_rtype = True
+# typehints_use_rtype = False
+# typehints_defaults = 'braces'
+# simplify_optional_unions = False
+
 # -- Intersphinx Settings ---------------------------------------------------------------------
 
 intersphinx_mapping = {
@@ -149,5 +184,3 @@
 todo_include_todos = True
 todo_emit_warnings = False
 todo_link_only = False
-
-# -- Viewcode Settings ------------------------------------------------------------------------

docs/docsrc/howto/howto-docstring.rst

@@ -40,6 +40,10 @@ Directives
 Next to plain text, the content of your documentation can be created using *directives*,
 followed by a block of indented text.
 
+Directives are structural blocks inside the text of a documentation.
+They provide specific formatting for sections dedicated to e.g., function parameters,
+return values or exmaple code.
+
 For example, the *note* directive in plain rst code ::
 
     .. note:: Implementation
@@ -142,40 +146,60 @@ As a consequence, **we abstain from including type hints in docstrings** and kee
 This rule does not exclude custom linking and referencing in-text, where a developer feels the
 necessity to do so.
 
+.. rubric:: Google style directives
+
+Google style directives are aliases for standard directives, which simplify the usage and syntax.
+Besides the obligatory declaration of parameters, return values and raised errors,
+the PorePy style encourages the use of other sections to provide notes, example code usage, references, etc.
+
+For a list of all supported Google style directives,
+`see Google style docstring sections <https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections>`_.
+
+The compulsory order of directives inside a docstring is:
+
+    1. Examples, Note, ...
+    2. References, See Also
+    3. Parameters
+    4. Returns/ Yields
+    5. Raises
+
+Other rules:
+
+    * When using Google Style directives do not type additional text **between** and **after** the
+      directives References/See Also, Parameters, Returns/Yields and Raises.
+    * End every docstring with a blank line before \"\"\". This is especially important after
+      the *Returns:* directive and its indented block.
+
+.. note::
+    The Google Style directives are only valid when used inside docstrings,
+    but not so when used in .rst files. Keep this in mind, in case you deal with the .rst
+    structure of the webpage.
 
 Documenting variables
 ---------------------
 
-.. autodata:: example_docstrings.module_level_var_1
+.. autodata:: example_docstrings.example_var_1
+
+.. autodata:: example_docstrings.example_var_2
 
-.. autodata:: example_docstrings.module_level_var_2
+.. autodata:: example_docstrings.example_var_3
 
-.. autodata:: example_docstrings.module_level_var_3
+.. autodata:: example_docstrings.ExampleArrayLike
 
 Documenting functions
 ---------------------
 
-.. autofunction:: example_docstrings.module_level_function_1
+.. autofunction:: example_docstrings.example_function_1
 
-.. autofunction:: example_docstrings.module_level_function_2
+.. autofunction:: example_docstrings.example_function_2
 
-.. autofunction:: example_docstrings.module_level_function_3
+.. autofunction:: example_docstrings.example_function_3
 
-.. autofunction:: example_docstrings.module_level_function_4
+.. autofunction:: example_docstrings.example_function_4
 
-.. autofunction:: example_docstrings.example_generator
+.. autofunction:: example_docstrings.example_function_5
 
-.. rubric:: Directives inside docstrings
-
-* Write the directive blocks in the following order
-    1. Examples, Note
-    2. Parameters
-    3. Returns/ Yields
-    4. Raises
-* When using Google Style directives do not type additional text **between** and **after** the
-  directives Parameters, Returns/Yields and Raises.
-* End every docstring with a blank line before \"\"\". This is especially important after
-  the *Returns:* directive and its indented block.
+.. autofunction:: example_docstrings.example_generator
 
 Documenting classes
 -------------------