Skip to content

Commit bad9c6d

Browse files
agriyakhetarpalagriyakhetarpal
authored
Merge pull request #4 from pybamm-team/docs-template
Add templates and configuration for documentation
2 parents aef1945 + 59b8834 commit bad9c6d

File tree

8 files changed

+225
-19
lines changed

8 files changed

+225
-19
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,3 +123,6 @@ cython_debug/
123123
# and can be added to the global gitignore or merged into this file. For a more nuclear
124124
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
125125
#.idea/
126+
127+
# Code editor files and folders
128+
.vscode/

‎docs/conf.py‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import importlib.metadata
22

33
project = "pybamm-cookiecutter"
4-
copyright = "2023, Agriya Khetarpal"
4+
copyright = "2018-2023, The PyBaMM Team"
55
author = "Agriya Khetarpal"
66
version = release = importlib.metadata.version("pybamm_cookiecutter")
77

@@ -14,7 +14,6 @@
1414
"sphinx_copybutton",
1515
"sphinx_inline_tabs",
1616
"pydata_sphinx_theme",
17-
"hoverxref.extension",
1817
"nbsphinx",
1918
]
2019

‎noxfile.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
import nox
2+
3+
# Options to modify nox behaviour
4+
nox.options.reuse_existing_virtualenvs = True
5+
6+
@nox.session(name="docs")
7+
def build_docs(session):
8+
"""Build the documentation and load it in a browser tab, rebuilding on changes."""
9+
envbindir = session.bin
10+
session.install("-e", ".[docs]")
11+
with session.chdir("docs/"):
12+
session.run(
13+
"sphinx-autobuild",
14+
"-j",
15+
"auto",
16+
"--open-browser",
17+
"-qT",
18+
".",
19+
f"{envbindir}/../tmp/html",
20+
)

‎pyproject.toml‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,12 +35,22 @@ dependencies = ["pybamm"]
3535
dev = [
3636
"pytest >=6",
3737
"pytest-cov >=3",
38+
"nox",
39+
"pre-commit",
3840
]
3941
docs = [
4042
"sphinx",
41-
"myst_parser",
42-
"sphinx_copybutton",
4343
"pydata_sphinx_theme",
44+
"sphinx_design",
45+
"sphinx-copybutton",
46+
"myst-parser",
47+
"sphinx-inline-tabs",
48+
"sphinxcontrib-bibtex",
49+
"sphinx-autobuild",
50+
"sphinx-last-updated-by-git",
51+
"nbsphinx",
52+
"ipython",
53+
"sphinx-gallery",
4454
]
4555

4656
[project.urls]

‎src/pybamm_cookiecutter/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
"""
2-
Copyright (c) 2023 Agriya Khetarpal. All rights reserved.
2+
Copyright (c) 2023 The PyBaMM Team. All rights reserved.
33
44
pybamm-cookiecutter: A template for creating battery modeling projects based on PyBaMM
55
"""

‎{{cookiecutter.project_name}}/docs/conf.py‎

Lines changed: 156 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,176 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file contains an opinionated list of extensions and configuration options
4+
# used by the PyBaMM documentation.
5+
#
6+
# For a full list, see the Sphinx documentation for configuration options at
7+
# https://www.sphinx-doc.org/en/master/config
8+
#
9+
# More information about the configuration options used here can be found in the
10+
# configuration file for the PyBaMM documentation at
11+
# https://github.com/pybamm-team/PyBaMM/blob/develop/docs/conf.py
12+
#
13+
# The configuration options to adjust the PyData Sphinx Theme with can be found at
14+
# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/index.html
15+
16+
17+
import os
18+
import sys
119
import importlib.metadata
220

21+
22+
# ---- Project information ------------------------------------------------------------
23+
324
project = "{{ cookiecutter.project_name }}"
425
copyright = "{{ cookiecutter.__year }}, {{ cookiecutter.full_name }}"
526
author = "{{ cookiecutter.full_name }}"
627
version = release = importlib.metadata.version("{{ cookiecutter.__project_slug }}")
728

29+
# ---- Path configuration -------------------------------------------------------------
30+
31+
# Path for repository root
32+
sys.path.insert(0, os.path.abspath("../"))
33+
34+
# Path for local Sphinx extensions
35+
sys.path.append(os.path.abspath("./sphinxext/"))
36+
37+
# ---- General configuration ----------------------------------------------------------
38+
39+
# If your documentation needs a minimal Sphinx version, state it here.
40+
41+
# needs_sphinx = '1.0'
42+
43+
# The suffix(es) of source filenames. You may specify multiple suffixes as
44+
# a list of strings.
45+
source_suffix = [".rst", ".md"]
46+
47+
# List of patterns relative to the source directory that match files and
48+
# directories to ignore when looking for source files. This pattern also
49+
# affects the html_static_path and html_extra_path configuration options.
50+
exclude_patterns = [
51+
"_build",
52+
"**.ipynb_checkpoints",
53+
"Thumbs.db",
54+
".DS_Store",
55+
]
56+
57+
html_theme = "pydata_sphinx_theme"
58+
html_title = "%s v%s Manual" % (project, version)
59+
html_last_updated_fmt = "%Y-%m-%d"
60+
html_static_path = ["_static"]
61+
html_file_suffix = ".html"
62+
63+
# Add any logos and favicons for your hosted documentation here. The logo and the favicon
64+
# should be placed in the html_static_path directory listed above.
65+
# html_logo = "_static/logo.png"
66+
# html_favicon = "_static/favicon.png"
67+
68+
# Add any paths that contain custom static files (such as style sheets or JavaScript scripts)
69+
# in the html_static_path listed above. They are copied after the builtin static files, so a
70+
# file named "default.css" will overwrite the builtin "default.css".
71+
# html_css_files = ["custom.css"]
72+
# html_js_files = ["custom.js"]
73+
74+
# Suppress any warnings generated by Sphinx and/or by Sphinx extensions as
75+
# a list of strings. The following warnings are suppressed by default:
76+
suppress_warnings = ["git.too_shallow"]
77+
78+
# Add any paths that contain templates here, relative to this directory.
79+
templates_path = ["_templates"]
80+
81+
# The language for content autogenerated by Sphinx. Refer to the Sphinx documentation
82+
# for a list of supported language codes according to the IETF BCP 47 standard.
83+
language = "en"
84+
85+
# Add any Sphinx extension module names here in a list of strings. They can be
86+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. The
87+
# custom ones must be placed under the path specified for local Sphinx extensions
88+
# in the system path configuration above.
89+
890
extensions = [
9-
"myst_parser",
91+
# Sphinx extensions
1092
"sphinx.ext.autodoc",
1193
"sphinx.ext.intersphinx",
1294
"sphinx.ext.mathjax",
1395
"sphinx.ext.napoleon",
96+
# Local extensions under ./sphinxext/
97+
# Third-party extensions
98+
"myst_parser",
99+
"sphinx_design",
14100
"sphinx_copybutton",
15101
"sphinx_inline_tabs",
102+
"sphinxcontrib.bibtex",
103+
"sphinx_last_updated_by_git",
16104
"pydata_sphinx_theme",
17-
"hoverxref.extension",
18105
"nbsphinx",
106+
"IPython.sphinxext.ipython_console_highlighting",
19107
]
20108

21-
source_suffix = [".rst", ".md"]
22-
exclude_patterns = [
23-
"_build",
24-
"**.ipynb_checkpoints",
25-
"Thumbs.db",
26-
".DS_Store",
27-
".env",
28-
".venv",
29-
]
109+
# ---- Options for EPUB output --------------------------------------------------------
30110

31-
html_theme = "pydata_sphinx_theme"
111+
# Bibliographic Dublin Core information
112+
epub_title = project
113+
114+
# The unique identifier of the text. This can be a ISBN number or the project homepage
115+
# epub_identifier = ''
116+
117+
# A unique identification for the text
118+
# epub_uid = ''
119+
120+
# A list of files that should not be packed into the EPUB file
121+
epub_exclude_files = ["search.html"]
122+
123+
# ---- HTML theme configuration -------------------------------------------------------
124+
125+
# Theme options are theme-specific and customize the look and feel of a theme further.
126+
# For a list of options available for each theme, see the documentation for the theme.
127+
128+
# For a list of options available for the PyData Sphinx Theme, see the documentation at
129+
# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/index.html
130+
131+
html_theme_options = {
132+
# "logo": {
133+
# "image_light": "logo.png",
134+
# "image_dark": "logo.png",
135+
# },
136+
"icon_links": [
137+
{
138+
{%- if cookiecutter.platform == "github" %}
139+
"name": "GitHub",
140+
"icon": "fa-brands fa-square-github",
141+
{%- elif cookiecutter.platform == "gitlab" %}
142+
"name": "GitLab",
143+
"icon": "fa-brands fa-square-gitlab",
144+
{%- endif %}
145+
"url": "{{ cookiecutter.url }}",
146+
},
147+
{
148+
"name": "PyPI",
149+
"url": "https://pypi.org/project/{{ cookiecutter.project_name }}/",
150+
"icon": "fa-solid fa-box",
151+
},
152+
],
153+
"collapse_navigation": True,
154+
"navbar_end": ["theme-switcher", "navbar-icon-links"],
155+
"use_edit_page_button": True,
156+
"pygment_light_style": "xcode",
157+
"pygment_dark_style": "monokai",
158+
"footer_start": [
159+
"copyright",
160+
"sphinx-version",
161+
],
162+
"footer_end": [
163+
"theme-version",
164+
"last-updated",
165+
],
166+
}
167+
168+
# ---- Extension configuration --------------------------------------------------------
169+
170+
# Add any configuration options for Sphinx extensions here as per the documentation for
171+
# each extension. See the PyBaMM documentation at
172+
# https://github.com/pybamm-team/PyBaMM/blob/develop/docs/conf.py for examples of how
173+
# to configure Sphinx extensions for your project.
32174

33175
myst_enable_extensions = [
34176
"colon_fence",
@@ -43,3 +185,5 @@
43185
}
44186

45187
always_document_param_types = True
188+
napoleon_use_rtype = True
189+
napoleon_google_docstring = False

‎{{cookiecutter.project_name}}/noxfile.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
import nox
2+
3+
# Options to modify nox behaviour
4+
nox.options.reuse_existing_virtualenvs = True
5+
6+
@nox.session(name="docs")
7+
def build_docs(session):
8+
"""Build the documentation and load it in a browser tab, rebuilding on changes."""
9+
envbindir = session.bin
10+
session.install("-e", ".[docs]")
11+
with session.chdir("docs/"):
12+
session.run(
13+
"sphinx-autobuild",
14+
"-j",
15+
"auto",
16+
"--open-browser",
17+
"-qT",
18+
".",
19+
f"{envbindir}/../tmp/html",
20+
)

‎{{cookiecutter.project_name}}/pyproject.toml‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,12 +47,22 @@ dependencies = ["pybamm"]
4747
dev = [
4848
"pytest >=6",
4949
"pytest-cov >=3",
50+
"nox",
51+
"pre-commit",
5052
]
5153
docs = [
5254
"sphinx",
53-
"myst_parser",
54-
"sphinx_copybutton",
5555
"pydata_sphinx_theme",
56+
"sphinx_design",
57+
"sphinx-copybutton",
58+
"myst-parser",
59+
"sphinx-inline-tabs",
60+
"sphinxcontrib-bibtex",
61+
"sphinx-autobuild",
62+
"sphinx-last-updated-by-git",
63+
"nbsphinx",
64+
"ipython",
65+
"sphinx-gallery",
5666
]
5767

5868
[project.urls]

0 commit comments

Comments
 (0)