Skip to content

Commit 14465c3

Browse files
LeonidElkinLeonidElkin
committed
docs: sphinx init
1 parent 19a9d36 commit 14465c3

15 files changed

Lines changed: 510 additions & 2 deletions

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,3 +125,9 @@ poetry.lock
125125
# refer to https://docs.cursor.com/context/ignore-files
126126
.cursorignore
127127
.cursorindexingignore
128+
129+
# Docs
130+
131+
docs/build/*
132+
docs/source/api/*
133+
docs/source/examples/*

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ exclude: >
1919
| \.gitignore$
2020
| LICENSE$
2121
| .*\.md$
22+
| .*\.jpg$
2223
)$
2324
2425
repos:

‎docs/Makefile‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
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 = poetry run sphinx-build
8+
SPHINXAPIDOC = poetry run sphinx-apidoc
9+
SOURCEDIR = source
10+
BUILDDIR = build
11+
12+
# Put it first so that "make" without argument is like "make help".
13+
help:
14+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
15+
16+
.PHONY: help Makefile
17+
18+
# Catch-all target: route all unknown targets to Sphinx using the new
19+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
20+
21+
# Generate API rst files (mirrors src/ package tree)
22+
.PHONY: api
23+
api:
24+
@poetry run python "$(SOURCEDIR)/generate_api.py"
25+
26+
# Build HTML after regenerating API
27+
html: api
28+
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
29+
30+
%: Makefile
31+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/source/_static/PySATL-icon.jpg‎

1.65 MB
Loading

‎docs/source/_static/PySATL-logo.jpg‎

115 KB
Loading

‎docs/source/_static/custom.css‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/* Code */
2+
.highlight {
3+
border-radius: 5px;
4+
padding: 1em;
5+
}
6+
7+
/* Tables */
8+
table {
9+
border-collapse: collapse;
10+
margin: 1em 0;
11+
}
12+
13+
table, th, td {
14+
border: 1px solid #ddd;
15+
}
16+
17+
th, td {
18+
padding: 8px;
19+
text-align: left;
20+
}
21+
22+
/* Header improvements */
23+
h1, h2, h3, h4, h5, h6 {
24+
margin-top: 1.5em;
25+
margin-bottom: 0.5em;
26+
}
27+
28+
/* Copy button */
29+
.copybtn {
30+
opacity: 0.3;
31+
transition: opacity 0.3s;
32+
}
33+
34+
.copybtn:hover {
35+
opacity: 1;
36+
}

‎docs/source/changelog.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Changelog
2+
=========
3+
4+
Version 0.0.1a0 (Alpha)
5+
------------------------
6+
7+
* Initial release with core functionality
8+
* Basic distribution framework
9+
* Family system for parametric distributions
10+
* Computation strategies and sampling methods

‎docs/source/conf.py‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
import os
2+
import sys
3+
from datetime import datetime
4+
5+
sys.path.insert(0, os.path.abspath("../../src"))
6+
7+
project = "PySATL Core"
8+
copyright = f"{datetime.now().year}, Leonid Elkin, Mikhail Mikhailov"
9+
author = "Leonid Elkin, Mikhail Mikhailov"
10+
release = "0.0.1a0"
11+
12+
extensions = [
13+
"sphinx.ext.autodoc",
14+
"sphinx.ext.napoleon",
15+
"sphinx.ext.viewcode",
16+
"sphinx.ext.intersphinx",
17+
"sphinx.ext.mathjax",
18+
"sphinx.ext.githubpages",
19+
"sphinx_rtd_theme",
20+
"myst_nb",
21+
"sphinx_autodoc_typehints",
22+
"sphinx_copybutton",
23+
"sphinx.ext.autosummary",
24+
]
25+
autosummary_generate = True
26+
templates_path = ["_templates"]
27+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
28+
29+
# -- Napoleon (NumPy style docstrings) --
30+
napoleon_google_docstring = False
31+
napoleon_use_keyword = True
32+
napoleon_numpy_docstring = True
33+
napoleon_include_init_with_doc = True
34+
napoleon_include_private_with_doc = False
35+
napoleon_include_special_with_doc = True
36+
napoleon_use_admonition_for_examples = True
37+
napoleon_use_admonition_for_notes = True
38+
napoleon_use_admonition_for_references = True
39+
napoleon_use_ivar = False
40+
napoleon_use_param = True
41+
napoleon_use_rtype = True
42+
napoleon_preprocess_types = True
43+
napoleon_type_aliases = None
44+
45+
# -- Autodocumentation settings --
46+
autodoc_default_options = {
47+
"member-order": "bysource",
48+
"special-members": "__init__",
49+
"undoc-members": True,
50+
"exclude-members": "__weakref__",
51+
"show-inheritance": True,
52+
}
53+
54+
autodoc_typehints = "description"
55+
autodoc_typehints_format = "short"
56+
57+
# -- Intersphinx --
58+
intersphinx_mapping = {
59+
"python": ("https://docs.python.org/3", None),
60+
"numpy": ("https://numpy.org/doc/stable/", None),
61+
"scipy": ("https://docs.scipy.org/doc/scipy/", None),
62+
}
63+
64+
# -- MyST Parser --
65+
myst_enable_extensions = [
66+
"amsmath",
67+
"colon_fence",
68+
"deflist",
69+
"dollarmath",
70+
"fieldlist",
71+
"html_admonition",
72+
"html_image",
73+
"linkify",
74+
"replacements",
75+
"smartquotes",
76+
"tasklist",
77+
]
78+
myst_heading_anchors = 3
79+
nb_execution_mode = "off"
80+
81+
# -- HTML --
82+
html_theme = "sphinx_rtd_theme"
83+
html_static_path = ["_static"]
84+
html_css_files = [
85+
"custom.css",
86+
]
87+
88+
# ReadTheDocs
89+
html_theme_options = {
90+
"collapse_navigation": False,
91+
"sticky_navigation": True,
92+
"navigation_depth": 4,
93+
"includehidden": True,
94+
"titles_only": False,
95+
"logo_only": False,
96+
}
97+
98+
# Sidebar: show navigation tree, avoid listing all members of the current page
99+
html_sidebars = {
100+
"**": [
101+
"about.html",
102+
"navigation.html",
103+
"relations.html",
104+
"searchbox.html",
105+
]
106+
}
107+
108+
html_logo = "_static/PySATL-logo.jpg"
109+
html_favicon = "_static/PySATL-icon.jpg"
110+
111+
# -- Compile --
112+
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
113+
copybutton_prompt_is_regexp = True
114+
copybutton_line_continuation_character = "\\"
115+
116+
source_suffix = {
117+
".rst": "restructuredtext",
118+
".md": "markdown",
119+
".ipynb": "myst-nb",
120+
}
121+
122+
suppress_warnings = [
123+
# 'autodoc.duplicate_object',
124+
"ref.misc",
125+
]
126+
127+
# forward references (actually don't matter too much but better be here)
128+
autodoc_type_aliases = {
129+
"In": "typing.Any",
130+
"Out": "typing.Any",
131+
"DistributionType": "pysatl_core.types.DistributionType",
132+
"Kind": "pysatl_core.types.Kind",
133+
"SamplingStrategy": "pysatl_core.distributions.strategies.SamplingStrategy",
134+
"ComputationStrategy": "pysatl_core.distributions.strategies.ComputationStrategy",
135+
"Parametrization": "pysatl_core.families.parametrizations.Parametrization",
136+
"Support": "pysatl_core.distributions.support.Support",
137+
"Sample": "pysatl_core.distributions.sampling.Sample",
138+
"Distribution": "pysatl_core.distributions.distribution.Distribution",
139+
"ParametricFamily": "pysatl_core.families.parametric_family.ParametricFamily",
140+
}
141+
142+
# Some checks
143+
nitpicky = False

‎docs/source/contributing.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Contributing
2+
============
3+
4+
See the full contributing guide in our `GitHub repository <https://github.com/PySATL/pysatl-core/blob/main/CONTRIBUTING.md>`_.

0 commit comments

Comments
 (0)