|
1 | | -# Configuration file for the Sphinx documentation builder. |
2 | | -# |
3 | | -# This file only contains a selection of the most common options. For a full |
4 | | -# list see the documentation: |
5 | | -# https://www.sphinx-doc.org/en/master/usage/configuration.html |
6 | | - |
7 | | -# -- Path setup -------------------------------------------------------------- |
8 | | - |
9 | | -# If extensions (or modules to document with autodoc) are in another directory, |
10 | | -# add these directories to sys.path here. If the directory is relative to the |
11 | | -# documentation root, use os.path.abspath to make it absolute, like shown here. |
12 | | -# |
13 | | -# import os |
14 | 1 | import os |
15 | 2 | import sys |
| 3 | +import shutil |
16 | 4 |
|
17 | 5 | # The module you're documenting (assumes you've added the project root dir to sys.path) |
18 | 6 | sys.path.insert(0, os.path.abspath('../..')) |
| 7 | +import PEPit |
19 | 8 |
|
20 | 9 | # -- Project information ----------------------------------------------------- |
21 | | - |
22 | 10 | project = 'PEPit' |
23 | 11 | copyright = '2021, PEPit Contributors' |
24 | 12 | author = 'PEPit Contributors' |
|
32 | 20 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom |
33 | 21 | # ones. |
34 | 22 | extensions = [ |
35 | | - # 'easydev.copybutton', |
36 | 23 | 'sphinx.ext.autodoc', |
37 | 24 | 'sphinx.ext.doctest', |
38 | 25 | 'sphinx.ext.intersphinx', |
|
43 | 30 | 'sphinx.ext.viewcode', |
44 | 31 | 'sphinx.ext.napoleon', |
45 | 32 | 'sphinx.ext.autosummary', |
46 | | - # 'sphinxcontrib_autodocgen', |
47 | | - 'myst_parser', |
| 33 | + 'myst_nb', |
48 | 34 | ] |
49 | 35 |
|
50 | | -napoleon_custom_sections = [('Returns', 'params_style'), |
51 | | - ('Attributes', 'params_style')] |
| 36 | +source_suffix = { |
| 37 | + '.rst': 'restructuredtext', |
| 38 | + '.md': 'markdown', |
| 39 | + '.ipynb': 'myst-nb', |
| 40 | +} |
52 | 41 |
|
53 | | -import PEPit |
| 42 | +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints'] |
| 43 | +templates_path = ['_templates'] |
| 44 | + |
| 45 | +# -- MyST & Notebook Settings ------------------------------------------------ |
| 46 | +nb_execution_mode = "off" |
| 47 | +myst_title_to_header = True |
| 48 | +myst_dmath_allow_labels = False # Disable MyST labels to stop double-numbering |
| 49 | +myst_update_mathjax = False # Let MathJax 3 handle its own configuration |
| 50 | +myst_dmath_double_inline = True |
| 51 | + |
| 52 | +myst_enable_extensions = [ |
| 53 | + "dollarmath", |
| 54 | + "amsmath", |
| 55 | + "colon_fence", |
| 56 | + "deflist", |
| 57 | + "html_image", |
| 58 | + "html_admonition", |
| 59 | +] |
| 60 | + |
| 61 | +# -- MathJax 3 Settings ------------------------------------------------------ |
| 62 | +mathjax3_config = { |
| 63 | + 'tex': { |
| 64 | + 'inlineMath': [['$', '$'], ['\\(', '\\)']], |
| 65 | + 'displayMath': [['$$', '$$'], ['\\[', '\\]']], |
| 66 | + 'processEscapes': True, |
| 67 | + 'tags': 'ams', # AMS numbering (1), (2) on the right |
| 68 | + 'useLabelIds': True |
| 69 | + }, |
| 70 | + 'options': { |
| 71 | + 'processHtmlClass': 'tex2jax_process|mathjax_process|math|output_area', |
| 72 | + } |
| 73 | +} |
| 74 | + |
| 75 | +# -- HTML Output Settings --------------------------------------------------- |
| 76 | +html_theme = 'sphinx_rtd_theme' |
| 77 | +html_static_path = ['_static'] |
| 78 | +html_secnumber_suffix = " " |
54 | 79 |
|
| 80 | +# -- Napoleon settings ------------------------------------------------------- |
| 81 | +napoleon_google_docstring = True |
| 82 | +napoleon_numpy_docstring = True |
| 83 | +napoleon_include_init_with_doc = False |
| 84 | +napoleon_include_private_with_doc = False |
| 85 | +napoleon_include_special_with_doc = False |
| 86 | + |
| 87 | +# -- Napoleon & Autodoc ----------------------------------------------------- |
| 88 | +napoleon_custom_sections = [('Returns', 'params_style'), ('Attributes', 'params_style')] |
| 89 | +autoclass_content = 'both' |
55 | 90 | autodocgen_config = [{ |
56 | 91 | 'modules': [PEPit], |
57 | 92 | 'generated_source_dir': './autodocgen-output/', |
58 | 93 |
|
59 | | - # if module matches this then it and any of its submodules will be skipped |
| 94 | + # Skips any module with "__" in the name or specific internal modules |
60 | 95 | 'skip_module_regex': '(.*[.]__|myskippedmodule)', |
61 | 96 |
|
62 | | - # produce a text file containing a list of everything documented. you can use this in a test to notice |
63 | | - # when you've intentionally added/removed/changed a documented API |
| 97 | + # Log file to track exactly what is being documented |
64 | 98 | 'write_documented_items_output_file': 'autodocgen_documented_items.txt', |
65 | 99 |
|
66 | | - # customize autodoc on a per-module basis |
| 100 | + # Custom options for specific classes if needed |
67 | 101 | 'autodoc_options_decider': { |
68 | | - 'mymodule.FooBar': {'inherited-members': True}, |
| 102 | + 'PEPit.FooBar': {'inherited-members': True}, |
69 | 103 | }, |
70 | 104 |
|
71 | | - # choose a different title for specific modules, e.g. the toplevel one |
72 | | - 'module_title_decider': lambda modulename: 'API Reference' if modulename == 'mymodule' else modulename, |
| 105 | + # Renames the top-level module to "API Reference" in the TOC |
| 106 | + 'module_title_decider': lambda modulename: 'API Reference' if modulename == 'PEPit' else modulename, |
73 | 107 | }] |
74 | 108 |
|
75 | | -autoclass_content = 'both' |
76 | | - |
77 | | -# Include or not the special methods |
78 | | -napoleon_include_special_with_doc = False |
| 109 | +# -- Automated Notebook Copying --------------------------------------------- |
| 110 | +current_dir = os.path.dirname(__file__) |
| 111 | +nb_source = os.path.abspath(os.path.join(current_dir, '../../ressources/demo/')) |
| 112 | +nb_dest = os.path.join(current_dir, 'notebooks_folder') |
79 | 113 |
|
80 | | -# Add any paths that contain templates here, relative to this directory. |
81 | | -templates_path = ['_templates'] |
| 114 | +if os.path.exists(nb_dest): |
| 115 | + shutil.rmtree(nb_dest) |
| 116 | +os.makedirs(nb_dest) |
82 | 117 |
|
83 | | -# List of patterns, relative to source directory, that match files and |
84 | | -# directories to ignore when looking for source files. |
85 | | -# This pattern also affects html_static_path and html_extra_path. |
86 | | -exclude_patterns = [] |
| 118 | +if os.path.exists(nb_source): |
| 119 | + for file in os.listdir(nb_source): |
| 120 | + if file.endswith('.ipynb'): |
| 121 | + shutil.copy2(os.path.join(nb_source, file), os.path.join(nb_dest, file)) |
87 | 122 |
|
88 | | -# -- Options for HTML output ------------------------------------------------- |
89 | 123 |
|
90 | | -# The theme to use for HTML and HTML Help pages. See the documentation for |
91 | | -# a list of builtin themes. |
92 | | -# |
93 | | -html_theme = 'sphinx_rtd_theme' |
94 | | - |
95 | | -# # Make the copy paste possible for any example code in documentation |
96 | | -# import easydev |
97 | | -# |
98 | | -# jscopybutton_path = easydev.copybutton.get_copybutton_path() |
99 | | -# |
100 | | -# # if not os.path.isdir('_static'): |
101 | | -# # os.mkdir('_static') |
102 | | -# |
103 | | -# import shutil |
104 | | -# |
105 | | -# shutil.copy(jscopybutton_path, '_static') |
106 | | - |
107 | | -# Add any paths that contain custom static files (such as style sheets) here, |
108 | | -# relative to this directory. They are copied after the builtin static files, |
109 | | -# so a file named "default.css" will overwrite the builtin "default.css". |
110 | | -html_static_path = ['_static'] |
| 124 | +# -- Setup Function --------------------------------------------------------- |
| 125 | +def setup(app): |
| 126 | + app.add_css_file('custom.css') |
0 commit comments