Skip to content

Commit 0f133d3

Browse files
stefsmeetsstefsmeets
authored
Add sphinx docs (#12)
* Add sphinx docs
1 parent 0a072ed commit 0f133d3

9 files changed

Lines changed: 228 additions & 0 deletions

File tree

‎docs/Makefile‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
# You can set these variables from the command line.
4+
SPHINXOPTS ?=
5+
SPHINXBUILD ?= sphinx-build
6+
SPHINXGEN ?= sphinx-apidoc
7+
SPHINXPROJ = edtools
8+
PYTHON ?= python
9+
PIP ?= pip
10+
SOURCEDIR = .
11+
BUILDDIR = _build
12+
TEMPLATESDIR = _templates
13+
STATICDIR = _static
14+
15+
html: conf.py edtools.rst readme.rst
16+
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
17+
18+
readme.rst: ../README.md
19+
pandoc --from=markdown --to=rst --output=readme.rst ../README.md
20+
21+
edtools.rst:
22+
$(SPHINXGEN) -eTf -t "$(TEMPLATESDIR)" -o "$(SOURCEDIR)" ../edtools
23+
24+
install.rst:
25+
touch install.rst
26+
27+
clean:
28+
rm -rvf "$(BUILDDIR)" "$(STATICDIR)/examples" edtools*.rst readme.rst

‎docs/_templates/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Contains apidoc templates from https://github.com/sphinx-doc/sphinx/tree/master/sphinx/templates/apidoc

‎docs/_templates/module.rst_t‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{{ basename | e | heading }}
2+
3+
.. automodule:: {{ qualname }}
4+
{%- for option in automodule_options %}
5+
:{{ option }}:
6+
{%- endfor %}

‎docs/_templates/package.rst_t‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{{ pkgname | e | heading }}
2+
{% if subpackages or submodules %}
3+
.. toctree::
4+
{% for docname in (subpackages or []) + (submodules or []) %}
5+
{{ docname }}
6+
{%- endfor %}
7+
{% endif %}
8+
.. automodule:: {{ pkgname }}
9+
{%- for option in automodule_options %}
10+
:{{ option }}:
11+
{%- endfor %}

‎docs/_templates/toc.rst_t‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{{ header | heading }}
2+
3+
.. toctree::
4+
:maxdepth: {{ maxdepth }}
5+
{% for docname in docnames %}
6+
{{ docname }}
7+
{%- endfor %}

‎docs/conf.py‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
import sys
2+
from pathlib import Path
3+
4+
root = Path(__file__).absolute().parent.parent
5+
sys.path.insert(0, str(root))
6+
7+
DOCSDIR = '.'
8+
BUILDDIR = '_build'
9+
TEMPLATESDIR = '_templates'
10+
STATICDIR = '_static'
11+
SOURCEDIR = '../edtools'
12+
13+
14+
# -- Run apidoc plug-in manually, as readthedocs doesn't support it -------
15+
# See https://github.com/rtfd/readthedocs.org/issues/1139
16+
def run_apidoc(app):
17+
ignore_paths = []
18+
19+
cmd = ('--separate --no-toc --force --module-first '
20+
f'-t {TEMPLATESDIR} '
21+
f'-o {DOCSDIR} '
22+
f'{SOURCEDIR} ')
23+
24+
args = cmd.split() + ignore_paths
25+
26+
from sphinx.ext import apidoc
27+
apidoc.main(args)
28+
29+
30+
# Convert readme.md and others to rst to be included in index.html
31+
def make_markdown(app):
32+
import subprocess
33+
for inp, out in (('../README.md', 'readme.rst'),):
34+
cmd = f'pandoc --from=markdown --to=rst --output={out} {inp}'
35+
args = cmd.split()
36+
subprocess.run(args)
37+
38+
39+
# https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
40+
# https://github.com/readthedocs/readthedocs.org/issues/2276
41+
def setup(app):
42+
app.connect('builder-inited', make_markdown)
43+
app.connect('builder-inited', run_apidoc)
44+
45+
46+
extensions = [
47+
'sphinx.ext.autodoc',
48+
# 'sphinx.ext.coverage',
49+
# 'sphinx.ext.doctest',
50+
# 'sphinx.ext.intersphinx',
51+
# 'sphinx.ext.mathjax',
52+
'sphinx.ext.napoleon',
53+
# 'nbsphinx',
54+
# 'nbsphinx_link',
55+
# 'sphinx.ext.todo',
56+
# 'sphinx.ext.viewcode',
57+
'autodocsumm',
58+
]
59+
60+
# Add any paths that contain templates here, relative to this directory.
61+
templates_path = ['_templates']
62+
63+
# The suffix(es) of source filenames.
64+
# You can specify multiple suffix as a list of string:
65+
source_suffix = ['.rst', '.md']
66+
67+
# The master toctree document.
68+
master_doc = 'index'
69+
70+
# General information about the project.
71+
project = 'edtools'
72+
copyright = '2021, '
73+
author = 'Stef Smeets'
74+
75+
# The short X.Y version.
76+
version = release = '1.0.0'
77+
78+
# The language for content autogenerated by Sphinx.
79+
language = 'english'
80+
81+
# List of patterns, relative to source directory, that match files and
82+
# directories to ignore when looking for source files.
83+
# This patterns also effect to html_static_path and html_extra_path
84+
exclude_patterns = [BUILDDIR, 'Thumbs.db', '.DS_Store']
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".
89+
html_static_path = [STATICDIR]
90+
91+
# The name of the Pygments (syntax highlighting) style to use.
92+
pygments_style = 'sphinx'
93+
94+
# If true, `todo` and `todoList` produce output, else they produce nothing.
95+
todo_include_todos = False
96+
97+
# Use autoapi.extension to run sphinx-apidoc
98+
autoapi_dirs = [SOURCEDIR]
99+
100+
# The theme to use for HTML and HTML Help pages. See the documentation for
101+
# a list of builtin themes.
102+
html_theme = 'sphinx_rtd_theme'
103+
# options for rtd-theme
104+
# html_theme_options = {
105+
# 'display_version': True,
106+
# 'prev_next_buttons_location': 'bottom',
107+
# 'style_external_links': False,
108+
# # toc options
109+
# 'collapse_navigation': True,
110+
# 'sticky_navigation': True,
111+
# 'navigation_depth': 4,
112+
# 'includehidden': True,
113+
# 'titles_only': False,
114+
# }
115+
116+
autodoc_default_options = {
117+
'autosummary': True,
118+
'special-members': '__init__',
119+
}
120+
121+
autodoc_mock_imports = [
122+
'cctbx',
123+
'iotbx',
124+
'importlib_metadata'
125+
]
126+
127+
intersphinx_mapping = {
128+
'python': ('https://docs.python.org/3', None),
129+
'numpy': ('https://docs.scipy.org/doc/numpy/', None),
130+
'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
131+
'scikit-image': ('https://scikit-image.org/docs/stable/', None),
132+
'matplotlib': ('https://matplotlib.org/stable/', None),
133+
}

‎docs/index.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
.. include:: readme.rst
2+
3+
4+
5+
API Reference
6+
=============
7+
8+
.. toctree::
9+
:maxdepth: 2
10+
:caption: API reference
11+
12+
edtools
13+
14+
15+
Links
16+
=====
17+
.. toctree::
18+
:caption: Links
19+
20+
🔗 Source code <http://github.com/instamatic-dev/instamatic>
21+
🔗 Issues <http://github.com/instamatic-dev/instamatic/issues>
22+
23+
24+
Indices and tables
25+
==================
26+
27+
* :ref:`genindex`
28+
* :ref:`modindex`
29+
* :ref:`search`

‎docs/make_docs.bat‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
python -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html

‎docs/requirements.txt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
sphinx
2+
sphinx_rtd_theme
3+
readthedocs-sphinx-search
4+
autodocsumm
5+
lmfit
6+
matplotlib
7+
numpy
8+
pandas
9+
pyyaml
10+
scipy
11+
scikit-image
12+
uncertainties

0 commit comments

Comments
 (0)