Docs/improve the doc

.gitignore

@@ -137,3 +137,4 @@ dmypy.json
 # Documentation
 docs/autodocgen-output
 docs/build
+docs/source/notebooks_folder

PEPit/pep.py

@@ -44,10 +44,11 @@ class PEP(object):
         _list_of_psd_sent_to_wrapper (list): list of :class:`PSDMatrix` objects actually sent to the wrapper.
 
         objective (Expression): the expression to be maximized by the solver.
-                                It is set by the method `solve`. And should not be updated otherwise.
+                                It is set by the method `solve`.
+                                And should not be updated otherwise.
 
         G_value (ndarray): the value of the Gram matrix G that the solver found.
-        F_value (ndarray): the value of the vector of :class:`Expression`s F that the solver found.
+        F_value (ndarray): the value of the vector of :class:`Expression` F that the solver found.
 
         residual (ndarray): the dual value found by the solver to the lmi constraints G >> 0.
 

PEPit/wrapper.py

@@ -16,8 +16,9 @@ class Wrapper(object):
 
     Attributes:
         _list_of_constraints_sent_to_solver (list): list of :class:`Constraint` and :class:`PSDMatrix` objects
-                                                    associated to the PEP. This list does not contain constraints
-                                                    due to internal representation of the problem by the solver.
+                                                    associated to the :class:`PEP`.
+                                                    This list does not contain constraints due to internal
+                                                    representation of the problem by the solver.
         optimal_F (numpy.array): Elements of F after solving.
         optimal_G (numpy.array): Gram matrix of the PEP after solving.
         objective (Expression): The objective expression that must be maximized.
@@ -30,9 +31,9 @@ class Wrapper(object):
         solver_name (str): The name of the solver the wrapper interact with.
         verbose (int): Level of information details to print (Override the solver verbose parameter).
 
-                       - 0: No verbose at all
-                       - 1: PEPit information is printed but not solver's
-                       - 2: Both PEPit and solver details are printed
+                       - 0: No verbose at all.
+                       - 1: PEPit information is printed but not solver's.
+                       - 2: Both PEPit and solver details are printed.
 
     """
 
@@ -44,9 +45,9 @@ def __init__(self, verbose=1):
         Args:
             verbose (int): Level of information details to print (Override the solver verbose parameter).
 
-                           - 0: No verbose at all
-                           - 1: PEPit information is printed but not solver's
-                           - 2: Both PEPit and solver details are printed
+                           - 0: No verbose at all.
+                           - 1: PEPit information is printed but not solver's.
+                           - 2: Both PEPit and solver details are printed.
 
         """
         # Initialize lists of constraints that are used to solve the SDP.
@@ -131,8 +132,9 @@ def assign_dual_values(self):
             residual (ndarray): main dual PSD matrix (dual to the PSD constraint on the Gram matrix).
 
         Raises:
-            TypeError if the attribute `_list_of_constraints_sent_to_solver` of this object
-            is neither a :class:`Constraint` object, nor a :class:`PSDMatrix` one.
+            TypeError
+                if the attribute `_list_of_constraints_sent_to_solver` of this object is neither
+                a :class:`Constraint` object, nor a :class:`PSDMatrix` one.
 
         """
         dual_values, residual = self._recover_dual_values()

docs/requirements.txt

@@ -1,6 +1,6 @@
 sphinx
 sphinx-autodocgen
 sphinx-rtd-theme
-myst-parser
+myst-nb
 easydev
 -r ../requirements.txt

docs/source/_static/custom.css

@@ -0,0 +1,21 @@
+/* 1. Fix the double math numbering */
+/* This targets the MyST-generated label that floats above the equation */
+div.myst-math-label {
+    display: none !important;
+}
+
+/* 2. Layout Fixes */
+/* Ensures the actual MathJax number on the right has space */
+div.math {
+    overflow: visible !important;
+    width: 100%;
+}
+
+/* 3. Kill the 'ghost' equation numbers generated by Sphinx/MyST */
+span.eqno {
+    display: none !important;
+    visibility: hidden !important;
+    position: absolute !important; /* Move it out of the layout flow */
+    width: 0 !important;
+    height: 0 !important;
+}

docs/source/conf.py

@@ -1,24 +1,12 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
 import os
 import sys
+import shutil
 
 # The module you're documenting (assumes you've added the project root dir to sys.path)
 sys.path.insert(0, os.path.abspath('../..'))
+import PEPit
 
 # -- Project information -----------------------------------------------------
-
 project = 'PEPit'
 copyright = '2021, PEPit Contributors'
 author = 'PEPit Contributors'
@@ -32,7 +20,6 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    # 'easydev.copybutton',
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
@@ -43,68 +30,97 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
     'sphinx.ext.autosummary',
-    # 'sphinxcontrib_autodocgen',
-    'myst_parser',
+    'myst_nb',
 ]
 
-napoleon_custom_sections = [('Returns', 'params_style'),
-                            ('Attributes', 'params_style')]
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+    '.ipynb': 'myst-nb',
+}
 
-import PEPit
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
+templates_path = ['_templates']
+
+# -- MyST & Notebook Settings ------------------------------------------------
+nb_execution_mode = "off"
+myst_title_to_header = True
+myst_dmath_allow_labels = False    # Disable MyST labels to stop double-numbering
+myst_update_mathjax = False        # Let MathJax 3 handle its own configuration
+myst_dmath_double_inline = True
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "html_image",
+    "html_admonition",
+]
+
+# -- MathJax 3 Settings ------------------------------------------------------
+mathjax3_config = {
+    'tex': {
+        'inlineMath': [['$', '$'], ['\\(', '\\)']],
+        'displayMath': [['$$', '$$'], ['\\[', '\\]']],
+        'processEscapes': True,
+        'tags': 'ams',             # AMS numbering (1), (2) on the right
+        'useLabelIds': True
+    },
+    'options': {
+        'processHtmlClass': 'tex2jax_process|mathjax_process|math|output_area',
+    }
+}
+
+# -- HTML Output Settings ---------------------------------------------------
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_secnumber_suffix = " "
 
+# -- Napoleon settings -------------------------------------------------------
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = False
+
+# -- Napoleon & Autodoc -----------------------------------------------------
+napoleon_custom_sections = [('Returns', 'params_style'), ('Attributes', 'params_style')]
+autoclass_content = 'both'
 autodocgen_config = [{
     'modules': [PEPit],
     'generated_source_dir': './autodocgen-output/',
 
-    # if module matches this then it and any of its submodules will be skipped
+    # Skips any module with "__" in the name or specific internal modules
     'skip_module_regex': '(.*[.]__|myskippedmodule)',
 
-    # produce a text file containing a list of everything documented. you can use this in a test to notice
-    # when you've intentionally added/removed/changed a documented API
+    # Log file to track exactly what is being documented
     'write_documented_items_output_file': 'autodocgen_documented_items.txt',
 
-    # customize autodoc on a per-module basis
+    # Custom options for specific classes if needed
     'autodoc_options_decider': {
-        'mymodule.FooBar': {'inherited-members': True},
+        'PEPit.FooBar': {'inherited-members': True},
     },
 
-    # choose a different title for specific modules, e.g. the toplevel one
-    'module_title_decider': lambda modulename: 'API Reference' if modulename == 'mymodule' else modulename,
+    # Renames the top-level module to "API Reference" in the TOC
+    'module_title_decider': lambda modulename: 'API Reference' if modulename == 'PEPit' else modulename,
 }]
 
-autoclass_content = 'both'
-
-# Include or not the special methods
-napoleon_include_special_with_doc = False
+# -- Automated Notebook Copying ---------------------------------------------
+current_dir = os.path.dirname(__file__)
+nb_source = os.path.abspath(os.path.join(current_dir, '../../ressources/demo/'))
+nb_dest = os.path.join(current_dir, 'notebooks_folder')
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+if os.path.exists(nb_dest):
+    shutil.rmtree(nb_dest)
+os.makedirs(nb_dest)
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+if os.path.exists(nb_source):
+    for file in os.listdir(nb_source):
+        if file.endswith('.ipynb'):
+            shutil.copy2(os.path.join(nb_source, file), os.path.join(nb_dest, file))
 
-# -- 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 = 'sphinx_rtd_theme'
-
-# # Make the copy paste possible for any example code in documentation
-# import easydev
-#
-# jscopybutton_path = easydev.copybutton.get_copybutton_path()
-#
-# # if not os.path.isdir('_static'):
-# #     os.mkdir('_static')
-#
-# import shutil
-#
-# shutil.copy(jscopybutton_path, '_static')
-
-# 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']
+# -- Setup Function ---------------------------------------------------------
+def setup(app):
+    app.add_css_file('custom.css')

docs/source/index.rst

@@ -14,6 +14,7 @@ Welcome to PEPit's documentation!
    quickstart
    api
    examples
+   tutorials
    whatsnew
    contributing
 

docs/source/tutorials.rst

@@ -0,0 +1,9 @@
+Tutorials
+=========
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   Finding worst-case guarantees <notebooks_folder/PEPit_demo.ipynb>
+   Extracting a proof <notebooks_folder/PEPit_demo_extracting_a_proof.ipynb>