Browse code

[docs] Set up documentation source and building machinery

Joseph Weston authored on 09/11/2019 13:59:02
Showing 9 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,2 @@
1
+# This is generated automatically by sphinx-apidoc
2
+reference/
0 3
new file mode 120000
... ...
@@ -0,0 +1 @@
1
+../CHANGELOG.md
0 2
\ No newline at end of file
1 3
new file mode 120000
... ...
@@ -0,0 +1 @@
1
+../LICENSE
0 2
\ No newline at end of file
1 3
new file mode 100644
2 4
new file mode 100644
3 5
new file mode 100644
... ...
@@ -0,0 +1,83 @@
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
+# sys.path.insert(0, os.path.abspath('.'))
16
+
17
+import os
18
+
19
+import qsim
20
+
21
+
22
+# -- Project information -----------------------------------------------------
23
+
24
+project = "qsim"
25
+copyright = "2019, Joseph Weston"
26
+author = "Joseph Weston"
27
+version = qsim.__version__
28
+release = qsim.__version__
29
+
30
+
31
+# -- General configuration ---------------------------------------------------
32
+
33
+# Add any Sphinx extension module names here, as strings. They can be
34
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
35
+# ones.
36
+extensions = [
37
+    "sphinx.ext.autodoc",
38
+    "sphinx.ext.autosummary",
39
+    "sphinx.ext.autosectionlabel",
40
+    "sphinx.ext.viewcode",  # View source code from documentation pages
41
+    "sphinx.ext.napoleon",  # numpy-style docstrings
42
+    "sphinxcontrib.apidoc",  # Run sphinx-apidoc when building
43
+    "m2r",
44
+]
45
+# Add any paths that contain templates here, relative to this directory.
46
+templates_path = ["_templates"]
47
+
48
+# List of patterns, relative to source directory, that match files and
49
+# directories to ignore when looking for source files.
50
+# This pattern also affects html_static_path and html_extra_path.
51
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
52
+
53
+default_role = "autolink"
54
+
55
+# -- Extension configuration -------------------------------------------------
56
+
57
+napoleon_google_docstring = False
58
+
59
+autosummary_generate = True
60
+
61
+apidoc_module_dir = os.path.dirname(qsim.__file__)
62
+apidoc_output_dir = "reference"
63
+apidoc_separate_modules = True
64
+apidoc_toc_file = False
65
+apidoc_module_first = True
66
+apidoc_extra_args = ["--force"]
67
+
68
+
69
+# -- Options for HTML output -------------------------------------------------
70
+
71
+# The theme to use for HTML and HTML Help pages.  See the documentation for
72
+# a list of builtin themes.
73
+#
74
+html_theme = "sphinx_rtd_theme"
75
+
76
+# Add any paths that contain custom static files (such as style sheets) here,
77
+# relative to this directory. They are copied after the builtin static files,
78
+# so a file named "default.css" will overwrite the builtin "default.css".
79
+html_static_path = ["_static"]
80
+
81
+# The license file has no extension, so Sphinx ignores it by default, so we
82
+# must add it here
83
+html_extra_path = ["LICENSE"]
0 84
new file mode 100644
... ...
@@ -0,0 +1,14 @@
1
+.. qsim documentation master file, created by
2
+   sphinx-quickstart on Sat Nov  9 13:45:58 2019.
3
+   You can adapt this file completely to your liking, but it should at least
4
+   contain the root `toctree` directive.
5
+
6
+.. mdinclude:: ../README.md
7
+
8
+.. toctree::
9
+   :maxdepth: 2
10
+   :hidden:
11
+   :caption: Contents:
12
+
13
+   CHANGELOG
14
+   reference/qsim
... ...
@@ -24,6 +24,9 @@ test = [
24 24
     "tox",
25 25
     "flake8-per-file-ignores",
26 26
 ]
27
-doc = [
27
+docs = [
28 28
     "sphinx",
29
+    "sphinx-rtd-theme",
30
+    "m2r",  # markdown support
31
+    "sphinxcontrib.apidoc",  # run sphinx-apidoc when building docs
29 32
 ]
... ...
@@ -47,6 +47,11 @@ deps = coverage
47 47
 skip_install = true
48 48
 commands = coverage erase
49 49
 
50
+[testenv:docs]
51
+changedir=docs
52
+deps = .[docs]
53
+commands = sphinx-build . _build
54
+
50 55
 [flake8]
51 56
 max-line-length = 100
52 57
 ignore =