diff --git a/docs/requirements.txt b/docs/requirements.txt index 6cceae1..63ea9be 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..16d1b13 --- /dev/null +++ b/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; +} diff --git a/docs/source/calfem_reference.rst b/docs/source/calfem_reference.rst index 79bdcf3..d0865f5 100644 --- a/docs/source/calfem_reference.rst +++ b/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: diff --git a/docs/source/conf.py b/docs/source/conf.py index 666a1b6..9f12a43 100644 --- a/docs/source/conf.py +++ b/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,36 +114,37 @@ # 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 @@ -150,7 +152,8 @@ #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 # " v 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 + + diff --git a/docs/source/developer.rst b/docs/source/developer.rst index 6da5b4d..12dc747 100644 --- a/docs/source/developer.rst +++ b/docs/source/developer.rst @@ -1,5 +1,5 @@ Developing CALFEM for Python -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +============================ Creating an environment for development --------------------------------------- diff --git a/docs/source/examples/exm7.ipynb b/docs/source/examples/exm7.ipynb index 582ac87..2bc8340 100644 --- a/docs/source/examples/exm7.ipynb +++ b/docs/source/examples/exm7.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Example 7\n", + "# Mesh example: Temperature distribution in a plate\n", "\n", "Meshing 8-node-isoparametric elements (second order incomplete quads). Shows use of surfacemarkers/elementmarkers to apply different properties to elements in different regions. " ] diff --git a/docs/source/exs1.rst b/docs/source/exs1.rst index 722eb51..674660f 100644 --- a/docs/source/exs1.rst +++ b/docs/source/exs1.rst @@ -1,5 +1,5 @@ Example: Connected springs -------------------------------------- +-------------------------- This example is from the CALFEM manual (exs1.py). diff --git a/docs/source/index.rst b/docs/source/index.rst index 0086f56..d698d57 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,9 +3,6 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -.. image:: images/calfem.logo.png - :scale: 20 % - CALFEM for Python - Documentation ================================= @@ -16,37 +13,13 @@ Contents: .. toctree:: :maxdepth: 1 - :caption: Installation installation - -.. toctree:: - :maxdepth: 2 - :caption: Tutorial - - calfem_examples - exs1 - examples/exs2 - examples/exs3 - examples/exs4 - examples/exs7 - calfem_mesh_guide - examples/exm1 - examples/exm2 - examples/exm3 - examples/exm6 - examples/exm10 - -.. toctree:: - :maxdepth: 1 - :caption: Developing - + using_calfem + mesh_guide developer - -.. toctree:: - :maxdepth: 1 - :caption: Function Reference - + standard_examples + mesh_examples calfem_reference diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 6f84383..f8e90ab 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,5 +1,5 @@ Installation instructions -^^^^^^^^^^^^^^^^^^^^^^^^^ +========================= The simplest way to install CALFEM for Python is via pip. This procedure will ensure that all required dependencies are fulfilled. diff --git a/docs/source/mesh_examples.rst b/docs/source/mesh_examples.rst new file mode 100644 index 0000000..2996637 --- /dev/null +++ b/docs/source/mesh_examples.rst @@ -0,0 +1,26 @@ +Mesh Examples +============= + +This section contains examples focused on mesh generation and geometry creation using CALFEM for Python's mesh module. These examples demonstrate how to create complex geometries, generate meshes, and visualize results. + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + examples/exm2 + examples/exm3 + examples/exm6 + examples/exm7 + examples/exm10 + examples/exm13 + +These examples cover: + +* **Basic geometry creation** - Creating simple and complex geometries +* **B-Splines and arcs** - Advanced geometric modeling +* **Mesh generation** - Creating finite element meshes +* **Boundary conditions** - Setting up markers and boundary conditions +* **Mesh refinement** - Controlling element density and quality +* **Visualization** - Displaying geometries and meshes + +The mesh examples build upon each other, starting with basic concepts and progressing to more advanced techniques for creating and manipulating finite element meshes. diff --git a/docs/source/calfem_mesh_guide.rst b/docs/source/mesh_guide.rst similarity index 100% rename from docs/source/calfem_mesh_guide.rst rename to docs/source/mesh_guide.rst diff --git a/docs/source/standard_examples.rst b/docs/source/standard_examples.rst new file mode 100644 index 0000000..cd7dd5f --- /dev/null +++ b/docs/source/standard_examples.rst @@ -0,0 +1,24 @@ +Standard Examples +================= + +This section contains standard finite element examples that demonstrate the basic steps in finite element calculations using CALFEM for Python. These examples show fundamental concepts like element matrices, assembly, solving systems of equations, and evaluating element forces. + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + exs1 + examples/exs2 + examples/exs3 + examples/exs4 + examples/exs7 + +These examples cover: + +* **Connected springs** - Basic finite element procedure +* **Heat flow** - One-dimensional heat transfer analysis +* **Bar structures** - Structural analysis with bar elements +* **Beam analysis** - Beam element calculations +* **Various other fundamental examples** + +Each example includes detailed explanations of the finite element method concepts and step-by-step Python implementations. diff --git a/docs/source/calfem_examples.rst b/docs/source/using_calfem.rst similarity index 95% rename from docs/source/calfem_examples.rst rename to docs/source/using_calfem.rst index f615142..6712d99 100644 --- a/docs/source/calfem_examples.rst +++ b/docs/source/using_calfem.rst @@ -19,21 +19,16 @@ CALFEM Python modules --------------------- * **calfem.core** - * Element routines * System routines * **calfem.utils** - * I/O routines * Misc. routines * **calfem.geometry** - * Routines for defining problem geometry used for input in mesh generation * **calfem.mesh** - * Mesh generation routines * **calfem.vis/calfem.vis_mpl** - * Routines for visualising geometry, meshes and results. Examples @@ -41,9 +36,8 @@ Examples The example codes show what CALFEM can do for you. The examples are divided into two: - Numerical examples - - Mesh examples -The next is tutorial on using Calfem for Python for numerical finite element, i.e., solving FEM equation to obtain nodal displacements given loading forces and +The next is tutorial on using CALFEM for Python for numerical finite element, i.e., solving FEM equation to obtain nodal displacements given loading forces and stiffness matrix. The example can be found in `examples` directories both on calfem-python root directory (for .py files) and docs directory (for .ipynb files).