Skip to content

Commit af66b36

Browse files
h-chmerukh-chmeruk
authored
Add docs folder (#21)
1 parent 0f2308d commit af66b36

File tree

11 files changed

+432
-0
lines changed

11 files changed

+432
-0
lines changed

‎template/docs/Makefile.jinja‎

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.
5+
SPHINXOPTS =
6+
SPHINXBUILD = python -msphinx
7+
SPHINXPROJ = {{ project_slug }}
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)

‎template/docs/api_reference.rst.jinja‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. _api_reference:
2+
3+
API Reference
4+
=============
5+
6+
The following gives detailed information about all {{ project_slug }} functions sorted
7+
according to their modules.
8+
9+
For examples on how to use {{ project_slug }} refer to the notebooks in the
10+
`examples gallery`_ and the documentation on classes and modules below.
11+
12+
13+
Modules
14+
-------
15+
16+
.. toctree::
17+
:maxdepth: 1
18+
19+
modules/{{ project_slug }}
20+
21+
22+
.. _examples gallery: https://pyfar-gallery.readthedocs.io/en/latest/examples_gallery.html

‎template/docs/conf.py.jinja‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
import os
10+
import sys
11+
import urllib3
12+
import shutil
13+
import numpy as np
14+
sys.path.insert(0, os.path.abspath('..'))
15+
16+
import {{ project_slug }} # noqa
17+
18+
# -- General configuration ---------------------------------------------------
19+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
20+
21+
extensions = [
22+
'sphinx.ext.autodoc',
23+
'sphinx.ext.viewcode',
24+
'sphinx.ext.napoleon',
25+
'sphinx.ext.autosummary',
26+
'matplotlib.sphinxext.plot_directive',
27+
'sphinx.ext.mathjax',
28+
'sphinx.ext.intersphinx',
29+
'autodocsumm',
30+
'sphinx_design',
31+
'sphinx_favicon',
32+
'sphinx_reredirects',
33+
'sphinx_mdinclude',
34+
]
35+
36+
# show tocs for classes and functions of modules using the autodocsumm
37+
# package
38+
autodoc_default_options = {'autosummary': True}
39+
40+
# show the code of plots that follows the command .. plot:: based on the
41+
# package matplotlib.sphinxext.plot_directive
42+
plot_include_source = True
43+
44+
# Add any paths that contain templates here, relative to this directory.
45+
templates_path = ['_templates']
46+
47+
# The suffix(es) of source filenames.
48+
# You can specify multiple suffix as a list of string:
49+
source_suffix = {
50+
'.rst': 'restructuredtext',
51+
'.md': 'markdown',
52+
}
53+
54+
# The master toctree document.
55+
master_doc = 'index'
56+
57+
# General information about the project.
58+
project = '{{ project_slug }}'
59+
copyright = "{{ copyright_statement }}"
60+
author = "{{ author }}"
61+
62+
# The version info for the project you're documenting, acts as replacement
63+
# for |version| and |release|, also used in various other places throughout
64+
# the built documents.
65+
#
66+
# The short X.Y version.
67+
version = {{ project_slug }}.__version__
68+
# The full version, including alpha/beta/rc tags.
69+
release = {{ project_slug }}.__version__
70+
71+
# This is also used if you do content translation via gettext catalogs.
72+
# Usually you set "language" from the command line for these cases.
73+
language = 'en'
74+
75+
# List of patterns, relative to source directory, that match files and
76+
# directories to ignore when looking for source files.
77+
# This patterns also effect to html_static_path and html_extra_path
78+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
79+
80+
# The name of the Pygments (syntax highlighting) style to use (Not defining
81+
# uses the default style of the html_theme).
82+
# pygments_style = 'sphinx'
83+
84+
# If true, '()' will be appended to :func: etc. cross-reference text.
85+
add_function_parentheses = False
86+
87+
# If true, `todo` and `todoList` produce output, else they produce nothing.
88+
todo_include_todos = False
89+
90+
# default language for highlighting in source code
91+
highlight_language = "python3"
92+
93+
# intersphinx mapping
94+
intersphinx_mapping = {
95+
{% if 'numpy' in dependencies -%}
96+
'numpy': ('https://numpy.org/doc/stable/', None),{% endif %}
97+
{% if 'scipy' in dependencies -%}
98+
'scipy': ('https://docs.scipy.org/doc/scipy/', None),{% endif %}
99+
{% if 'matplotlib' in dependencies -%}
100+
'matplotlib': ('https://matplotlib.org/stable/', None),{% endif %}
101+
{% if 'pyfar' in dependencies -%}
102+
'pyfar': ('https://pyfar.readthedocs.io/en/stable/', None),
103+
'gallery': ('https://pyfar-gallery.readthedocs.io/en/latest/', None),{% endif %}
104+
}
105+
106+
# -- Options for HTML output -------------------------------------------------
107+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
108+
109+
html_theme = 'pydata_sphinx_theme'
110+
html_static_path = ['_static']
111+
html_css_files = ['css/custom.css']
112+
html_js_files = ['js/custom.js']
113+
html_logo = '{{ logo_path_gallery }}'
114+
html_title = "{{ project_slug }}"
115+
html_favicon = '_static/favicon.ico'
116+
117+
# -- HTML theme options
118+
# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html
119+
html_sidebars = {
120+
"{{ project_slug }}": []
121+
}
122+
123+
html_theme_options = {
124+
"navbar_start": ["navbar-logo"],
125+
"navbar_end": ["navbar-icon-links", "theme-switcher"],
126+
"navbar_align": "content",
127+
"header_links_before_dropdown": None, # will be automatically set later based on headers.rst
128+
"header_dropdown_text": "Packages", # Change dropdown name from "More" to "Packages"
129+
"icon_links": [
130+
{
131+
"name": "GitHub",
132+
"url": "https://github.com/pyfar",
133+
"icon": "fa-brands fa-square-github",
134+
"type": "fontawesome",
135+
},
136+
],
137+
# Configure secondary (right) side bar
138+
"show_toc_level": 3, # Show all subsections of notebooks
139+
"secondary_sidebar_items": ["page-toc"], # Omit 'show source' link that that shows notebook in json format
140+
"navigation_with_keys": True,
141+
# Configure navigation depth for section navigation
142+
"navigation_depth": 2,
143+
}
144+
145+
html_context = {
146+
"default_mode": "light"
147+
}
148+
149+
# redirect index to pyfar.html
150+
redirects = {
151+
"index": "{{ project_slug }}.html"
152+
}
153+
154+
# -- download navbar and style files from gallery -----------------------------
155+
branch = 'main'
156+
link = f'https://github.com/pyfar/gallery/raw/{branch}/docs/'
157+
folders_in = [
158+
'_static/css/custom.css',
159+
'_static/js/custom.js',
160+
'_static/favicon.ico',
161+
'_static/header.rst',
162+
'{{ logo_path_gallery }}',
163+
]
164+
165+
def download_files_from_gallery(link, folders_in):
166+
c = urllib3.PoolManager()
167+
for file in folders_in:
168+
url = link + file
169+
filename = file
170+
os.makedirs(os.path.dirname(filename), exist_ok=True)
171+
with c.request('GET', url, preload_content=False) as res:
172+
if res.status == 200:
173+
with open(filename, 'wb') as out_file:
174+
shutil.copyfileobj(res, out_file)
175+
176+
download_files_from_gallery(link, folders_in)
177+
# if logo does not exist, use pyfar logo
178+
if not os.path.exists(html_logo):
179+
download_files_from_gallery(
180+
link, ['resources/logos/pyfar_logos_fixed_size_pyfar.png'])
181+
shutil.copyfile(
182+
'resources/logos/pyfar_logos_fixed_size_pyfar.png', html_logo)
183+
184+
185+
# -- modify downloaded header file from the gallery to ----------------------
186+
# -- aline with the local toctree ---------------------------------------------
187+
188+
# read the header file from the gallery
189+
with open("_static/header.rst", "rt") as fin:
190+
lines = [line for line in fin]
191+
192+
# replace readthedocs link with internal link to this documentation
193+
lines_mod = [
194+
line.replace(f'https://{project}.readthedocs.io', project) for line in lines]
195+
196+
# if not found, add this documentation link to the end of the list, so that
197+
# it is in the doc tree
198+
contains_project = any(project in line for line in lines_mod)
199+
if not contains_project:
200+
lines_mod.append(f' {project} <{project}>\n')
201+
202+
# write the modified header file
203+
# to the doc\header.rst folder, so that it can be used in the documentation
204+
with open("header.rst", "wt") as fout:
205+
fout.writelines(lines_mod)
206+
207+
208+
# -- find position of pyfar package in toctree --------------------------------
209+
# -- this is required to define the dropdown of Packages in the header --------
210+
211+
# find line where pyfar package is mentioned, to determine the start of
212+
# the packages list in the header
213+
n_line_pyfar = 0
214+
for i, line in enumerate(lines):
215+
if 'https://pyfar.readthedocs.io' in line:
216+
n_line_pyfar = i
217+
break
218+
219+
# the first 4 lines of the header file are defining the settings and a empty
220+
# line of the toctree, therefore we need to subtract 4 from the line number
221+
# of the pyfar package to get the correct position in the toctree
222+
n_toctree_pyfar = n_line_pyfar - 4
223+
224+
if n_toctree_pyfar < 1:
225+
raise ValueError(
226+
"Could not find the line where pyfar package is mentioned. "
227+
"Please check the header.rst file in the gallery."
228+
)
229+
230+
# set dropdown header at pyfar appearance, so that pyfar is the first item in
231+
# the dropdown called Packages
232+
html_theme_options['header_links_before_dropdown'] = n_toctree_pyfar

‎template/docs/contributing.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. include:: ../CONTRIBUTING.rst

‎template/docs/history.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. include:: ../HISTORY.rst

‎template/docs/index.rst.jinja‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{{ project_slug }}
2+
{% for _ in project_slug %}={% endfor %}
3+
4+
.. include:: header.rst

‎template/docs/make.bat.jinja‎

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

‎template/docs/modules/{{ project_slug }}.rst.jinja‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{{ project_slug }}
2+
{% for _ in project_slug %}={% endfor %}
3+
4+
.. automodule:: {{ project_slug }}
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎template/docs/readme.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. mdinclude:: ../README.md

0 commit comments

Comments
 (0)