Skip to content

Commit c827c6c

Browse files
h-chmerukh-chmeruk
committed
Added docs folder, added 2 additional tests
1 parent 0c61935 commit c827c6c

File tree

12 files changed

+420
-0
lines changed

12 files changed

+420
-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: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
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 -%}'numpy': ('https://numpy.org/doc/stable/', None),{% endif %}
96+
{% if 'scipy' in dependencies -%}
97+
'scipy': ('https://docs.scipy.org/doc/scipy/', None),{% endif %}
98+
{% if 'matplotlib' in dependencies -%}
99+
'matplotlib': ('https://matplotlib.org/stable/', None),{% endif %}
100+
{% if 'pyfar' in dependencies -%}
101+
'pyfar': ('https://pyfar.readthedocs.io/en/stable/', None),{% endif %}
102+
}
103+
104+
# -- Options for HTML output -------------------------------------------------
105+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
106+
107+
html_theme = 'pydata_sphinx_theme'
108+
html_static_path = ['_static']
109+
html_css_files = ['css/custom.css']
110+
html_js_files = ['js/custom.js']
111+
html_logo = '{{ logo_path_gallery }}'
112+
html_title = "{{ project_slug }}"
113+
html_favicon = '_static/favicon.ico'
114+
115+
# -- HTML theme options
116+
# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html
117+
html_sidebars = {
118+
"{{ project_slug }}": []
119+
}
120+
121+
html_theme_options = {
122+
"navbar_start": ["navbar-logo"],
123+
"navbar_end": ["navbar-icon-links", "theme-switcher"],
124+
"navbar_align": "content",
125+
"header_links_before_dropdown": None, # will be automatically set later based on headers.rst
126+
"header_dropdown_text": "Packages", # Change dropdown name from "More" to "Packages"
127+
"icon_links": [
128+
{
129+
"name": "GitHub",
130+
"url": "https://github.com/pyfar",
131+
"icon": "fa-brands fa-square-github",
132+
"type": "fontawesome",
133+
},
134+
],
135+
# Configure secondary (right) side bar
136+
"show_toc_level": 3, # Show all subsections of notebooks
137+
"secondary_sidebar_items": ["page-toc"], # Omit 'show source' link that that shows notebook in json format
138+
"navigation_with_keys": True,
139+
# Configure navigation depth for section navigation
140+
"navigation_depth": 2,
141+
}
142+
143+
html_context = {
144+
"default_mode": "light"
145+
}
146+
147+
# redirect index to pyfar.html
148+
redirects = {
149+
"index": "{{ project_slug }}.html"
150+
}
151+
152+
# -- download navbar and style files from gallery -----------------------------
153+
branch = 'main'
154+
link = f'https://github.com/pyfar/gallery/raw/{branch}/docs/'
155+
folders_in = [
156+
'_static/css/custom.css',
157+
'_static/js/custom.js',
158+
'_static/favicon.ico',
159+
'_static/header.rst',
160+
'{{ logo_path_gallery }}',
161+
]
162+
163+
def download_files_from_gallery(link, folders_in):
164+
c = urllib3.PoolManager()
165+
for file in folders_in:
166+
url = link + file
167+
filename = file
168+
os.makedirs(os.path.dirname(filename), exist_ok=True)
169+
with c.request('GET', url, preload_content=False) as res:
170+
if res.status == 200:
171+
with open(filename, 'wb') as out_file:
172+
shutil.copyfileobj(res, out_file)
173+
174+
download_files_from_gallery(link, folders_in)
175+
# if logo does not exist, use pyfar logo
176+
if not os.path.exists(html_logo):
177+
download_files_from_gallery(
178+
link, ['resources/logos/pyfar_logos_fixed_size_pyfar.png'])
179+
shutil.copyfile(
180+
'resources/logos/pyfar_logos_fixed_size_pyfar.png', html_logo)
181+
182+
183+
# -- modify downloaded header file from the gallery to ----------------------
184+
# -- aline with the local toctree ---------------------------------------------
185+
186+
# read the header file from the gallery
187+
with open("_static/header.rst", "rt") as fin:
188+
lines = [line for line in fin]
189+
190+
# replace readthedocs link with internal link to this documentation
191+
lines_mod = [
192+
line.replace(f'https://{project}.readthedocs.io', project) for line in lines]
193+
194+
# if not found, add this documentation link to the end of the list, so that
195+
# it is in the doc tree
196+
contains_project = any(project in line for line in lines_mod)
197+
if not contains_project:
198+
lines_mod.append(f' {project} <{project}>\n')
199+
200+
# write the modified header file
201+
# to the doc\header.rst folder, so that it can be used in the documentation
202+
with open("header.rst", "wt") as fout:
203+
fout.writelines(lines_mod)
204+
205+
206+
# -- find position of pyfar package in toctree --------------------------------
207+
# -- this is required to define the dropdown of Packages in the header --------
208+
209+
# find line where pyfar package is mentioned, to determine the start of
210+
# the packages list in the header
211+
n_line_pyfar = 0
212+
for i, line in enumerate(lines):
213+
if 'https://pyfar.readthedocs.io' in line:
214+
n_line_pyfar = i
215+
break
216+
217+
# the first 4 lines of the header file are defining the settings and a empty
218+
# line of the toctree, therefore we need to subtract 4 from the line number
219+
# of the pyfar package to get the correct position in the toctree
220+
n_toctree_pyfar = n_line_pyfar - 4
221+
222+
if n_toctree_pyfar < 1:
223+
raise ValueError(
224+
"Could not find the line where pyfar package is mentioned. "
225+
"Please check the header.rst file in the gallery."
226+
)
227+
228+
# set dropdown header at pyfar appearance, so that pyfar is the first item in
229+
# the dropdown called Packages
230+
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)