Skip to content

Commit e35e6b9

Browse files
thepabloaguilarthepabloaguilar
authored
Initial documentation structure (#91)
* Updates `.readthedocs.yml` * Substitutes `m2r` package in favor of `m2r2` * Inital documentation structure
1 parent cbd9cd6 commit e35e6b9

File tree

13 files changed

+273
-38
lines changed

13 files changed

+273
-38
lines changed

‎.readthedocs.yml‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
1-
---
2-
3-
build:
4-
image: latest
1+
version: 2
52

63
python:
7-
version: 3.6
4+
version: 3.7
5+
install:
6+
- requirements: docs/requirements.txt
7+
8+
sphinx:
9+
configuration: docs/conf.py
10+
fail_on_warning: true
11+
12+
formats: all

‎docs/.gitkeep‎

Whitespace-only changes.

‎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/_static/override.css‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.globaltoc > p.caption {
2+
display: block;
3+
font-size: 1.05em;
4+
font-weight: 700;
5+
text-decoration: none;
6+
margin-bottom: 1em;
7+
border: 0;
8+
}
9+
10+
/* For some reason it did not have a scroll attached. */
11+
12+
.mermaid {
13+
overflow: scroll;
14+
}

‎docs/_templates/layout.html‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{# layout.html #}
2+
{# Import the layout of the theme. #}
3+
{% extends "!layout.html" %}
4+
5+
{% set css_files = css_files + ['_static/overrides.css'] %}

‎docs/_templates/moreinfo.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<h3>
2+
Links
3+
</h3>
4+
<ul>
5+
<li>
6+
<a href="https://github.com/dry-python/lambdas">GitHub</a>
7+
</li>
8+
<li>
9+
<a href="https://pypi.python.org/pypi/lambdas">PyPI</a>
10+
</li>
11+
<li>
12+
<a href="https://app.codecov.io/gh/dry-python/lambdas/branch/master">Coverage</a>
13+
</li>
14+
</ul>

‎docs/conf.py‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
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('.'))
17+
18+
19+
# -- Project information -----------------------------------------------------
20+
21+
def _get_project_meta():
22+
import tomlkit # noqa: WPS433
23+
24+
with open('../pyproject.toml') as pyproject:
25+
file_contents = pyproject.read()
26+
27+
return tomlkit.parse(file_contents)['tool']['poetry']
28+
29+
30+
pkg_meta = _get_project_meta()
31+
project = 'lambdas'
32+
copyright = '2021, dry-python team'
33+
author = 'dry-python team'
34+
35+
# The short X.Y version
36+
version = str(pkg_meta['version'])
37+
# The full version, including alpha/beta/rc tags
38+
release = version
39+
40+
41+
# -- General configuration ---------------------------------------------------
42+
43+
# Add any Sphinx extension module names here, as strings. They can be
44+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
45+
# ones.
46+
extensions = [
47+
'sphinx.ext.autodoc',
48+
'sphinx.ext.doctest',
49+
'sphinx.ext.todo',
50+
'sphinx.ext.coverage',
51+
'sphinx.ext.viewcode',
52+
'sphinx.ext.autosummary',
53+
'sphinx.ext.napoleon',
54+
55+
# Used to include .md files:
56+
'm2r2',
57+
58+
# Used to insert typehints into the final docs:
59+
'sphinx_autodoc_typehints',
60+
]
61+
62+
autoclass_content = 'class'
63+
autodoc_member_order = 'bysource'
64+
65+
autodoc_default_options = {
66+
'members': True,
67+
'show-inheritance': True,
68+
}
69+
70+
# Set `typing.TYPE_CHECKING` to `True`:
71+
# https://pypi.org/project/sphinx-autodoc-typehints/
72+
set_type_checking_flag = False
73+
always_document_param_types = True
74+
75+
# Add any paths that contain templates here, relative to this directory.
76+
templates_path = ['_templates']
77+
78+
# The suffix(es) of source filenames.
79+
# You can specify multiple suffix as a list of string:
80+
source_suffix = ['.rst', '.md']
81+
82+
# List of patterns, relative to source directory, that match files and
83+
# directories to ignore when looking for source files.
84+
# This pattern also affects html_static_path and html_extra_path.
85+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
86+
87+
# The name of the Pygments (syntax highlighting) style to use.
88+
pygments_style = 'sphinx'
89+
90+
add_module_names = False
91+
92+
# -- Options for HTML output -------------------------------------------------
93+
94+
# The theme to use for HTML and HTML Help pages. See the documentation for
95+
# a list of builtin themes.
96+
html_theme = 'sphinx_typlog_theme'
97+
98+
# Theme options are theme-specific and customize the look and feel of a theme
99+
# further. For a list of options available for each theme, see the
100+
# documentation.
101+
html_theme_options = {
102+
'logo_name': 'lambdas',
103+
'description': (
104+
'Write short and fully-typed lambdas where you need them.'
105+
),
106+
'github_user': 'dry-python',
107+
'github_repo': 'lambdas',
108+
'color': '#E8371A',
109+
}
110+
111+
# Add any paths that contain custom static files (such as style sheets) here,
112+
# relative to this directory. They are copied after the builtin static files,
113+
# so a file named "default.css" will overwrite the builtin "default.css".
114+
html_static_path = ['_static']
115+
116+
# Custom sidebar templates, must be a dictionary that maps document names
117+
# to template names.
118+
html_sidebars = {
119+
'**': [
120+
'logo.html',
121+
'globaltoc.html',
122+
'github.html',
123+
'searchbox.html',
124+
'moreinfo.html',
125+
],
126+
}
127+
128+
# -- Extension configuration -------------------------------------------------
129+
130+
napoleon_numpy_docstring = False
131+
132+
# -- Options for todo extension ----------------------------------------------
133+
134+
# If true, `todo` and `todoList` produce output, else they produce nothing.
135+
todo_include_todos = True

‎docs/index.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.. mdinclude:: ../README.md
2+
3+
Contents
4+
--------
5+
6+
.. toctree::
7+
:maxdepth: 1
8+
:caption: Changelog
9+
10+
pages/changelog.rst
11+
12+
13+
Indices and tables
14+
------------------
15+
16+
* :ref:`genindex`
17+
* :ref:`modindex`
18+
* :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

‎docs/pages/changelog.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. mdinclude:: ../../CHANGELOG.md

0 commit comments

Comments
 (0)