Skip to content

Commit aaf8ab5

Browse files
guilgautierguilgautier
committed
initialize documentation
1 parent b3f21d1 commit aaf8ab5

File tree

11 files changed

+281
-0
lines changed

11 files changed

+281
-0
lines changed

‎README.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
- [Development environment](#development-environment)
55
- [Dependency management](#dependency-management)
66
- [Installation](#installation)
7+
- [Documentation](#documentation)
78
- [Miscellaneous](#miscellaneous)
89

910
This repository may serve as a template for scientific projects written in [Python](https://www.python.org/).
@@ -111,6 +112,22 @@ To install the package from source and potentially contribute to it
111112
# pip install ".[docs, notebook]" # install extra documentation and jupyter notebook dependencies (see pyproject.toml)
112113
```
113114

115+
## Documentation
116+
117+
[Sphinx](https://www.sphinx-doc.org/en/master/index.html) is recommended to generate the project's documentation.
118+
119+
The source files of the documentation are simply `.rst` (reStructuredText) or `.md` (Markdown) files.
120+
However we suggest using reST markup to keep the same syntax and format as used for [Python docstings](https://devguide.python.org/documenting/).
121+
122+
Sphinx is in charge of building the documentation and generates HTML output in the `docs/_buil`
123+
Note: Sphinx can also be set up to generate a PDF using LaTeX.
124+
125+
- Install `docs` extras dependencies, see `tool.poetry.extras` in [`pyproject.toml`](pyproject.toml)
126+
127+
```bash
128+
poetry install -E docs
129+
```
130+
114131
## Miscellaneous
115132

116133
Consider reading

‎docs/Makefile

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, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
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)

‎docs/bibliography/bibliography.bib

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
% This is a mock example, the references are not correct
2+
3+
@misc{Bringhurst2105,
4+
author = {Robert Bringhurst},
5+
edition = {3.1},
6+
isbn = {0-88179-215-5},
7+
keywords = {workshop},
8+
publisher = {Hartley \& Marks},
9+
title = {The Elements of Typography},
10+
year = {2105},
11+
}
12+
13+
@unpublished{Mittelbach2105,
14+
arxivid = {id},
15+
author = {Frank Mittelbach and Michel Goossens},
16+
code = {https://github.com},
17+
edition = {Second},
18+
isbn = {0-211-36299-6},
19+
note = {},
20+
publisher = {Addison--Wesley},
21+
title = {The \LaTeX\ Companion},
22+
url = {https://www.google.com/},
23+
video = {https://www.youtube.com/},
24+
year = {2105},
25+
}
26+
27+
@book{Tufte2106,
28+
author = {Edward R. Tufte},
29+
booktitle = {Beautiful Evidence},
30+
edition = {First},
31+
isbn = {0-9613921-7-7},
32+
month = {May},
33+
place = {Cheshire, Connecticut},
34+
publisher = {Graphics Press, {LLC}},
35+
title = {Beautiful Evidence},
36+
year = {2106},
37+
}
38+
39+
@book{Tufte2152,
40+
author = {Edward R. Tufte},
41+
booktitle = {Beautiful Evidence},
42+
edition = {First},
43+
isbn = {0-9613921-7-7},
44+
month = {May},
45+
place = {Cheshire, Connecticut},
46+
publisher = {Graphics Press, {LLC}},
47+
title = {Beautiful Evidence},
48+
year = {2152},
49+
}
50+
51+
@article{Tufte2990,
52+
address = {Cheshire, Connecticut},
53+
author = {Edward R. Tufte},
54+
isbn = {0-9613921-1-8},
55+
journal = {A journal},
56+
publisher = {Graphics Press},
57+
title = {Envisioning Information},
58+
year = {2990},
59+
}
60+
61+
@inproceedings{Tufte2997,
62+
address = {Cheshire, Connecticut},
63+
author = {Edward R. Tufte},
64+
booktitle = {Visual Explanations},
65+
isbn = {0-9613921-2-6},
66+
publisher = {Graphics Press},
67+
title = {Visual Explanations},
68+
year = {2997},
69+
}

‎docs/bibliography/index.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. setup defined in conf.py
2+
.. For more info checkout https://sphinxcontrib-bibtex.readthedocs.io/en/latest/index.html
3+
4+
Bibliography
5+
############
6+
7+
.. bibliography::
8+
:all:

‎docs/conf.py

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
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+
import sys
15+
16+
sys.path.insert(0, os.path.abspath("../src"))
17+
18+
19+
# -- Project information -----------------------------------------------------
20+
21+
project = "packagename"
22+
copyright = "2021, Guillaume Gautier"
23+
author = "Guillaume Gautier"
24+
25+
26+
# -- General configuration ---------------------------------------------------
27+
28+
# Add any Sphinx extension module names here, as strings. They can be
29+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
30+
# ones.
31+
extensions = [
32+
"sphinx.ext.doctest",
33+
"sphinx.ext.autodoc",
34+
"sphinx.ext.viewcode",
35+
"sphinx.ext.mathjax", # LaTeX math rendering
36+
"sphinxcontrib.bibtex", # Bibliography management
37+
]
38+
# "matplotlib.sphinxext.plot_directive" to generate matplotlib plots in the documentation
39+
# see https://matplotlib.org/stable/api/sphinxext_plot_directive_api.html
40+
41+
42+
# Add any paths that contain templates here, relative to this directory.
43+
templates_path = ["_templates"]
44+
html_static_path = ["_static"]
45+
46+
# List of patterns, relative to source directory, that match files and
47+
# directories to ignore when looking for source files.
48+
# This pattern also affects html_static_path and html_extra_path.
49+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
50+
51+
52+
# -- Options for HTML output -------------------------------------------------
53+
54+
# The theme to use for HTML and HTML Help pages. See the documentation for a list of builtin themes.
55+
# https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes
56+
# or third-party themes
57+
# https://sphinx-themes.org/
58+
html_theme = "alabaster"
59+
60+
# Add any paths that contain custom static files (such as style sheets) here,
61+
# relative to this directory. They are copied after the builtin static files,
62+
# so a file named "default.css" will overwrite the builtin "default.css".
63+
# html_static_path = ["_static"]
64+
65+
# -- Extension configuration -------------------------------------------------
66+
67+
# sphinxcontrib-bibtex https://sphinxcontrib-bibtex.readthedocs.io/en/latest/index.html
68+
bibtex_bibfiles = ["./bibliography/bibliography.bib"]
69+
bibtex_encoding = "latin"
70+
# bibtex_reference_style = "alpha" # alpha, plain , unsrt, and unsrtalpha

‎docs/feature_1/api.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
API
2+
===
3+
4+
.. automodule:: packagename.operations
5+
:members:
6+
:inherited-members:
7+
:show-inheritance:

‎docs/feature_1/definition.rst

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.. |fig1| image:: ../images/plus_symbol.png
2+
:width: 100%
3+
:alt: + symbol
4+
:align: middle
5+
6+
.. |cap1| replace:: my ``+`` symbol
7+
8+
9+
Section
10+
=======
11+
12+
+---------+---------+
13+
| |fig1| | |fig1| |
14+
+---------+---------+
15+
| |cap1| | |cap1| |
16+
+---------+---------+
17+
18+
subsection
19+
----------
20+
21+
subsubsection
22+
^^^^^^^^^^^^^
23+
24+
paragraph
25+
"""""""""

‎docs/feature_1/index.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Feature 1: operations
2+
=====================
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
definition
8+
api

‎docs/images/plus_symbol.png

4.22 KB
Loading

‎docs/index.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. packagename documentation master file, created by
2+
sphinx-quickstart on Fri Aug 20 14:41:15 2021.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to packagename's documentation!
7+
=======================================
8+
9+
This is a front page of the documentation
10+
11+
.. toctree::
12+
:maxdepth: 3
13+
14+
feature_1/index
15+
bibliography/index
16+
17+
Indices and tables
18+
==================
19+
20+
* :ref:`genindex`
21+
* :ref:`modindex`
22+
* :ref:`search`

‎docs/make.bat

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

0 commit comments

Comments
 (0)