Updated documentation

docs/requirements.txt

@@ -1,8 +1,12 @@
 visvis
-PyQt5
+numpy
+matplotlib
+scipy
+tabulate
+qtpy
+pyqt
 pyvtk
-calfem-python
 ipython_genutils==0.1.0
-sphinx==6.1
-nbsphinx==0.9.3
-sphinx-material
+sphinx
+nbsphinx
+furo

docs/source/_static/custom.css

@@ -0,0 +1,195 @@
+/* Custom CSS for CALFEM documentation */
+
+/* ===== FUNCTION SIGNATURES - INCREASE FONT SIZE ===== */
+.sig,
+dt.sig,
+dt.sig.sig-object,
+.py .sig {
+    font-size: 1.1em !important;  /* More modest increase */
+    font-weight: 500 !important;
+    line-height: 1.3 !important;
+    display: inline !important;  /* Ensure proper inline display */
+}
+
+/* Make function/method names more prominent but not too large */
+.sig-name,
+.py .sig-name.descname {
+    font-size: 1.15em !important;  /* Slightly larger but more reasonable */
+    font-weight: 600 !important;
+    color: var(--color-brand-primary) !important;
+}
+
+/* Keep parentheses and parameters in line */
+.sig-paren {
+    font-size: 1.1em !important;
+    font-weight: normal !important;
+}
+
+/* Parameter names in signatures */
+.sig-param {
+    font-size: 1.1em !important;
+    font-weight: normal !important;
+}
+
+.sig-param .n {
+    font-weight: 500 !important;
+}
+
+/* ===== DOCSTRING SECTION HEADERS - REDUCE FONT SIZE ===== */
+/* Target the actual h3 elements used for Parameters, Returns, etc. */
+.py .section h3 {
+    font-size: 0.5em !important;  /* Reduced from default ~1.2em */
+    font-weight: 700 !important;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    color: var(--color-foreground-muted) !important;
+    margin-top: 1.8em !important;
+    margin-bottom: 0.6em !important;
+    border-bottom: 1px solid var(--color-background-border) !important;
+    padding-bottom: 2px !important;
+}
+
+/* Also target any remaining .rubric elements */
+.rubric {
+    font-size: 0.8em !important;  /* Reduced from default ~1em */
+    font-weight: 700 !important;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    color: var(--color-foreground-muted) !important;
+    margin-top: 1.8em !important;
+    margin-bottom: 0.6em !important;
+    border-bottom: 1px solid var(--color-background-border) !important;
+    padding-bottom: 2px !important;
+}
+
+/* Field lists (Parameters, Returns, etc.) - cleaner styling */
+/* Target actual parameter names in definition lists */
+.py .section dl.simple dt {
+    font-size: 0.9em !important;  /* Parameter names */
+    font-weight: 600 !important;
+    color: var(--color-brand-primary) !important;
+    margin-right: 8px !important;
+    margin-bottom: 0.3em !important;
+}
+
+/* Parameter types (classifiers) */
+.py .section dl.simple dt .classifier {
+    font-size: 0.85em !important;
+    font-weight: normal !important;
+    color: var(--color-foreground-muted) !important;
+    font-style: italic !important;
+}
+
+/* Also target any remaining .field-name elements */
+.field-list .field-name {
+    font-size: 0.8em !important;  /* Smaller but not tiny */
+    font-weight: 600 !important;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    color: var(--color-foreground-muted) !important;
+    margin-right: 8px !important;
+}
+
+/* ===== VISUAL IMPROVEMENTS ===== */
+/* Parameter descriptions - keep readable */
+.field-list .field-body {
+    font-size: 0.95em !important;
+    line-height: 1.5 !important;
+    margin-left: 8px !important;
+}
+
+/* API documentation sections with subtle visual separation */
+.py.class > dt,
+.py.function > dt,
+.py.method > dt {
+    font-size: 1.1em !important;  /* More reasonable size */
+    border-left: 3px solid var(--color-brand-primary) !important;
+    padding-left: 12px !important;
+    padding-right: 8px !important;
+    margin-bottom: 8px !important;
+    background: rgba(var(--color-brand-primary-rgb), 0.05) !important;  /* Very subtle background */
+    padding-top: 6px !important;
+    padding-bottom: 6px !important;
+    border-radius: 0 4px 4px 0 !important;
+}
+
+/* Code examples in docstrings */
+.docstring .highlight pre {
+    font-size: 0.9em !important;
+    line-height: 1.5 !important;
+    border-radius: 6px !important;
+}
+
+/* ===== RESPONSIVE ADJUSTMENTS ===== */
+/* Adjust sizes for smaller screens */
+@media (max-width: 768px) {
+    .sig,
+    .sig-name,
+    .py .sig {
+        font-size: 1.1em !important;
+    }
+
+    .sig-name,
+    .py .sig-name.descname {
+        font-size: 1.2em !important;
+    }
+
+    .py .section h3,
+    .rubric,
+    .field-list .field-name {
+        font-size: 0.8em !important;
+    }
+}
+
+/* ===== ADDITIONAL ENHANCEMENTS ===== */
+/* Improve spacing between API items */
+.py.class,
+.py.function,
+.py.method {
+    margin-bottom: 2em !important;
+}
+
+/* Better spacing for nested elements */
+.py .py {
+    margin-left: 1em !important;
+    border-left: 2px solid var(--color-background-border) !important;
+    padding-left: 1em !important;
+}
+
+/* Highlight current item in navigation */
+.toctree-l1.current > a {
+    font-weight: 600 !important;
+    color: var(--color-brand-primary) !important;
+}
+
+/* ===== REMOVE BULLETS FROM MAIN TOC ===== */
+/* Remove bullets/numbers from main table of contents only (top level) */
+.toctree-wrapper > ul {
+    list-style: none !important;
+    padding-left: 0 !important;
+}
+
+/* Keep indentation for nested items */
+.toctree-wrapper ul ul {
+    padding-left: 1.5em !important;
+}
+
+.toctree-wrapper li {
+    margin-bottom: 0.5em !important;
+}
+
+/* Also remove from numbered lists if using :numbered: option (top level only) */
+.toctree-wrapper > ol {
+    list-style: none !important;
+    padding-left: 0 !important;
+    counter-reset: none !important;
+}
+
+/* Keep indentation for nested numbered lists */
+.toctree-wrapper ol ol {
+    padding-left: 1.5em !important;
+}
+
+.toctree-wrapper > ol > li::before {
+    display: none !important;
+}

docs/source/calfem_reference.rst

@@ -19,12 +19,6 @@ Mesh functions
 .. automodule:: calfem.mesh
    :members:
 
-User interface functions
-------------------------
-
-.. automodule:: calfem.ui
-   :members:
-
 Utility functions
 -----------------
 
@@ -37,14 +31,3 @@ Visualisation functions (Matplotlib)
 .. automodule:: calfem.vis_mpl
    :members:
 
-Visualisation functions (VisVis)
---------------------------------
-
-.. automodule:: calfem.vis
-   :members:
-
-Interactive Geometry Editor
----------------------------
-
-.. automodule:: calfem.editor
-   :members:

docs/source/conf.py

@@ -16,26 +16,27 @@
 import sys
 import os
 
-# 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.
-sys.path.insert(0, os.path.abspath('../..'))
-
 # -- General configuration ------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
-    'nbsphinx',           # to embedd ipynb files
-    'sphinx.ext.mathjax', # to enable latex
+    'nbsphinx',           # embed ipynb files
+    'sphinx.ext.mathjax', # enable LaTeX math
 ]
 
+# Disable problematic sphinx_immaterial extensions
+# sphinx_immaterial.nav_adapt is causing the synopses KeyError
+# We'll add back the theme functionality without the problematic nav_adapt
+
+# --- Autodoc type hints configuration -------------------------------------
+# Hide all type hints from function/class signatures and parameter lists in
+# the generated API documentation. Other valid values: 'description', 'both'.
+autodoc_typehints = 'none'
+# If future fine-grained control needed, you can instead use 'description' and
+# toggle autodoc_typehints_description_target.
+# autodoc_typehints_description_target = 'all'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -62,14 +63,14 @@
 # The short X.Y version.
 version = '3.6'
 # The full version, including alpha/beta/rc tags.
-release = '3.6.8'
+release = '3.6.12'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -113,44 +114,46 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_material'
+html_theme = 'furo'
 
-html_theme_options = {
+# Switch to furo theme - modern, clean, and responsive
+# html_theme = 'bootstrap'
+# html_theme = 'sphinx_material'
+# html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_immaterial'
 
-    # Set the name of the project to appear in the navigation.
-    'nav_title': 'CALFEM for Python',
-
-    # Set the color and the accent color
-    'color_primary': 'blue',
-    'color_accent': 'light-blue',
-
-    # Set the repo location to get a badge with stats
-    'repo_url': 'https://github.com/CALFEM/calfem-python/',
-    'repo_name': 'CALFEM for Python',
-
-    # Visible levels of the global TOC; -1 means unlimited
-    'globaltoc_depth': 3,
-    # If False, expand all TOC entries
-    'globaltoc_collapse': True,
-    # If True, show hidden TOC entries
-    'globaltoc_includehidden': False,
-    'logo_icon': "",
-    #'logo_icon': 'images/calfem.logo.sw.svg'
+# furo theme options
+html_theme_options = {
+    "source_repository": "https://github.com/CALFEM/calfem-python/",
+    "source_branch": "develop",
+    "source_directory": "docs/source/",
+    "sidebar_hide_name": True,
+    "light_css_variables": {
+        "color-brand-primary": "#1976d2",
+        "color-brand-content": "#1976d2",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#64b5f6",
+        "color-brand-content": "#64b5f6",
+    },
+    "navigation_with_keys": True,
 }
 
-html_sidebars = {
-    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
-}
 
-#html_logo = 'images/calfem.logo.png'
+# Let the theme manage its own navigation sidebars; the explicit sidebar
+# templates from sphinx-material are removed to avoid missing template errors.
+# html_sidebars = {}
+
+html_logo = 'images/calfem.logo.png'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+# import sphinx_bootstrap_theme
+# html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -171,7 +174,8 @@
 # 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']
+html_static_path = ['_static']
+html_css_files = ['custom.css']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -316,3 +320,5 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+

docs/source/developer.rst

@@ -1,5 +1,5 @@
 Developing CALFEM for Python
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+============================
 
 Creating an environment for development
 ---------------------------------------