Skip to content

Commit 94635b5

Browse files
jjcremmersjjcremmers
committed
Updating documentation
1 parent a66fb65 commit 94635b5

File tree

5 files changed

+103
-156
lines changed

5 files changed

+103
-156
lines changed

‎.github/workflows/documentation.yml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: documentation
2+
3+
on: [push, pull_request, workflow_dispatch]
4+
5+
permissions:
6+
contents: write
7+
8+
jobs:
9+
docs:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-python@v5
14+
- name: Install dependencies
15+
run: |
16+
pip install sphinx sphinx_rtd_theme myst_parser sphinx-autoapi h5py vtk numpy scipy
17+
- name: Sphinx build
18+
run: |
19+
sphinx-build doc _build
20+
- name: Deploy to GitHub Pages
21+
uses: peaceiris/actions-gh-pages@v3
22+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
23+
with:
24+
publish_branch: gh-pages
25+
github_token: ${{ secrets.GITHUB_TOKEN }}
26+
publish_dir: _build/
27+
force_orphan: true

‎doc/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/conf.py

Lines changed: 17 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -1,177 +1,40 @@
1-
# -*- coding: utf-8 -*-
2-
#
31
# Configuration file for the Sphinx documentation builder.
42
#
5-
# This file does only contain a selection of the most common options. For a
6-
# full list see the documentation:
7-
# http://www.sphinx-doc.org/en/master/config
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
85

9-
# -- Path setup --------------------------------------------------------------
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
108

11-
# If extensions (or modules to document with autodoc) are in another directory,
12-
# add these directories to sys.path here. If the directory is relative to the
13-
# documentation root, use os.path.abspath to make it absolute, like shown here.
14-
#
159
import os
1610
import sys
17-
sys.path.insert(0, os.path.abspath('..'))
18-
19-
20-
# -- Project information -----------------------------------------------------
11+
sys.path.insert(0, os.path.abspath('../'))
2112

2213
project = 'PyFEM'
23-
copyright = '2023, Joris Remmers'
14+
copyright = '2025, Joris Remmers'
2415
author = 'Joris Remmers'
2516

26-
# The short X.Y version
27-
version = ''
28-
# The full version, including alpha/beta/rc tags
29-
release = ''
30-
31-
3217
# -- General configuration ---------------------------------------------------
18+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
3319

34-
# If your documentation needs a minimal Sphinx version, state it here.
35-
#
36-
# needs_sphinx = '1.0'
37-
38-
# Add any Sphinx extension module names here, as strings. They can be
39-
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
40-
# ones.
4120
extensions = [
42-
'sphinx.ext.autodoc',
21+
'sphinx.ext.autodoc', # Automatically include docstrings
22+
'sphinx.ext.viewcode', # Add links to source code
23+
'sphinx.ext.napoleon', # Support for NumPy/Google-style docstrings
24+
'sphinx_rtd_theme', # Use the Read the Docs theme
25+
'sphinx.ext.mathjax',
4326
]
4427

45-
# Add any paths that contain templates here, relative to this directory.
4628
templates_path = ['_templates']
47-
48-
# The suffix(es) of source filenames.
49-
# You can specify multiple suffix as a list of string:
50-
#
51-
# source_suffix = ['.rst', '.md']
52-
source_suffix = '.rst'
53-
54-
# The master toctree document.
55-
master_doc = 'index'
56-
57-
# The language for content autogenerated by Sphinx. Refer to documentation
58-
# for a list of supported languages.
59-
#
60-
# This is also used if you do content translation via gettext catalogs.
61-
# Usually you set "language" from the command line for these cases.
62-
language = None
63-
64-
# List of patterns, relative to source directory, that match files and
65-
# directories to ignore when looking for source files.
66-
# This pattern also affects html_static_path and html_extra_path.
6729
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
6830

69-
# The name of the Pygments (syntax highlighting) style to use.
70-
pygments_style = None
31+
autodoc_default_flags = ['members', 'undoc-members', 'private-members']
32+
add_module_names = False
33+
autodoc_member_order = 'bysource'
7134

7235

7336
# -- Options for HTML output -------------------------------------------------
37+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
7438

75-
# The theme to use for HTML and HTML Help pages. See the documentation for
76-
# a list of builtin themes.
77-
#
78-
#html_theme = 'alabaster'
79-
80-
# Theme options are theme-specific and customize the look and feel of a theme
81-
# further. For a list of options available for each theme, see the
82-
# documentation.
83-
#
84-
# html_theme_options = {}
85-
86-
# Add any paths that contain custom static files (such as style sheets) here,
87-
# relative to this directory. They are copied after the builtin static files,
88-
# so a file named "default.css" will overwrite the builtin "default.css".
39+
html_theme = 'sphinx_rtd_theme'
8940
html_static_path = ['_static']
90-
91-
# Custom sidebar templates, must be a dictionary that maps document names
92-
# to template names.
93-
#
94-
# The default sidebars (for documents that don't match any pattern) are
95-
# defined by theme itself. Builtin themes are using these templates by
96-
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
97-
# 'searchbox.html']``.
98-
#
99-
# html_sidebars = {}
100-
101-
102-
# -- Options for HTMLHelp output ---------------------------------------------
103-
104-
# Output file base name for HTML help builder.
105-
htmlhelp_basename = 'PyFEMdoc'
106-
107-
108-
# -- Options for LaTeX output ------------------------------------------------
109-
110-
latex_elements = {
111-
# The paper size ('letterpaper' or 'a4paper').
112-
#
113-
# 'papersize': 'letterpaper',
114-
115-
# The font size ('10pt', '11pt' or '12pt').
116-
#
117-
# 'pointsize': '10pt',
118-
119-
# Additional stuff for the LaTeX preamble.
120-
#
121-
# 'preamble': '',
122-
123-
# Latex figure (float) alignment
124-
#
125-
# 'figure_align': 'htbp',
126-
}
127-
128-
# Grouping the document tree into LaTeX files. List of tuples
129-
# (source start file, target name, title,
130-
# author, documentclass [howto, manual, or own class]).
131-
latex_documents = [
132-
(master_doc, 'PyFEM.tex', 'PyFEM Documentation',
133-
'Joris Remmers', 'manual'),
134-
]
135-
136-
137-
# -- Options for manual page output ------------------------------------------
138-
139-
# One entry per manual page. List of tuples
140-
# (source start file, name, description, authors, manual section).
141-
man_pages = [
142-
(master_doc, 'pyfem', 'PyFEM Documentation',
143-
[author], 1)
144-
]
145-
146-
147-
# -- Options for Texinfo output ----------------------------------------------
148-
149-
# Grouping the document tree into Texinfo files. List of tuples
150-
# (source start file, target name, title, author,
151-
# dir menu entry, description, category)
152-
texinfo_documents = [
153-
(master_doc, 'PyFEM', 'PyFEM Documentation',
154-
author, 'PyFEM', 'One line description of project.',
155-
'Miscellaneous'),
156-
]
157-
158-
159-
# -- Options for Epub output -------------------------------------------------
160-
161-
# Bibliographic Dublin Core info.
162-
epub_title = project
163-
164-
# The unique identifier of the text. This can be a ISBN number
165-
# or the project homepage.
166-
#
167-
# epub_identifier = ''
168-
169-
# A unique identification for the text.
170-
#
171-
# epub_uid = ''
172-
173-
# A list of files that should not be packed into the epub file.
174-
epub_exclude_files = ['search.html']
175-
176-
177-
# -- Extension configuration -------------------------------------------------

‎doc/index.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
.. PyFEM documentation master file, created by
2-
sphinx-quickstart on Tue Mar 1 14:35:33 2022.
2+
sphinx-quickstart on Mon Dec 30 18:39:21 2024.
33
You can adapt this file completely to your liking, but it should at least
44
contain the root `toctree` directive.
55
66
PyFEM: A Python finite element code
77
===================================
88

9-
Contents:
9+
Add your content using ``reStructuredText`` syntax. See the
10+
`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
11+
documentation for details.
1012

1113
.. toctree::
1214
:maxdepth: 2

‎doc/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

0 commit comments

Comments
 (0)