Skip to content

Commit 947ee97

Browse files
mattkrammattkram
authored
Add documentation boilerplate (#28)
* Add documentation boilerplate * Integrate docs dependencies into pyproject.toml as extras * Add some information on building docs in CONTRIBUTING.md
1 parent f565b64 commit 947ee97

File tree

10 files changed

+264
-1
lines changed

10 files changed

+264
-1
lines changed

‎.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,7 @@ coverage.xml
2626

2727
# mypy
2828
.mypy_cache/
29+
30+
# Generated documentation
31+
/docs/build/
32+
/docs/source/api/

‎CONTRIBUTING.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Contribution guide for developers
2+
3+
## Documentation
4+
5+
### Install the documentation dependencies
6+
7+
To get started, you will need to install the documentation dependencies from the project root:
8+
9+
```shell
10+
poetry install --extras docs
11+
```
12+
13+
### The quickest way to get started
14+
15+
The following command (run from project root) will launch a live-reloaded session of the
16+
documentation in your browser, effectively combining the steps detailed in the following sections:
17+
18+
```shell
19+
poetry run make -C docs live
20+
```
21+
22+
### Activate the environment
23+
24+
You will need to activate the virtual environment in order to use the dependencies that were
25+
just installed:
26+
27+
```shell
28+
poetry shell
29+
```
30+
31+
Your prompt should now have a prefix, e.g.:
32+
33+
```shell
34+
(pyscript-cli-_y5OiBT8-py3.9) mattkram [~/dev/pyscript-cli] $
35+
```
36+
37+
### Generate the docs in live mode
38+
39+
The live mode will allow you to generate the documentation with live reload.
40+
41+
From the project root, run the following command :
42+
43+
```shell
44+
make -C docs live
45+
```
46+
47+
Or, alternately, navigate to the `docs` directory and run:
48+
49+
```shell
50+
make live
51+
```
52+
53+
54+
Either of the above commands should launch a live dev server and you will be able to view the
55+
docs in your browser.
56+
As the files are updated, the docs should be refreshed.
57+
58+
### Generate static docs
59+
60+
If you don't want to use the live reload mode, simply replace either command above with `html`,
61+
e.g.:
62+
63+
```shell
64+
make -C docs html
65+
```

‎docs/Makefile

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
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 = source
9+
BUILDDIR = build
10+
11+
# Internal variables.
12+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) source
13+
14+
# Put it first so that "make" without argument is like "make help".
15+
help:
16+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
17+
18+
.PHONY: help Makefile
19+
20+
.PHONY: api-docs
21+
api-docs:
22+
sphinx-apidoc -f -o source/api ../src/pyscript -H "API Docs"
23+
24+
.PHONY: html
25+
html: api-docs
26+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
27+
@echo
28+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
29+
30+
.PHONY: live
31+
live: api-docs
32+
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) --watch ../src --open-browser
33+
34+
# Catch-all target: route all unknown targets to Sphinx using the new
35+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
36+
%: Makefile
37+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat

+35
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=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
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/requirements.txt

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Install the documentation dependencies
2+
# This is required because readthedocs needs requirements.txt
3+
..[docs]

‎docs/source/_static/avatar.jpeg

10.6 KB
Loading

‎docs/source/conf.py

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
"""Documentation configuration for `pyscript-cli`."""
2+
from __future__ import annotations
3+
4+
import sys
5+
from datetime import datetime
6+
from pathlib import Path
7+
8+
import toml
9+
10+
# Ensure the package is in the path
11+
project_root = Path(__file__).parents[2]
12+
sys.path.insert(0, (project_root / "src").as_posix())
13+
14+
# General information about the project.
15+
project = "pyscript-cli"
16+
author = "Anaconda"
17+
copyright = f"2022 - {datetime.now().year}, {author}"
18+
19+
# Load the package version from pyproject.toml
20+
with (project_root / "pyproject.toml").open("r") as fp:
21+
version = toml.load(fp)["tool"]["poetry"]["version"]
22+
release = version
23+
24+
25+
# Add any Sphinx extension module names here, as strings. They can be
26+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
27+
# ones.
28+
extensions = [
29+
"myst_parser",
30+
"sphinx.ext.doctest",
31+
"sphinx.ext.intersphinx",
32+
"sphinx.ext.coverage",
33+
"sphinx.ext.mathjax",
34+
"sphinx.ext.autodoc",
35+
"sphinx.ext.napoleon",
36+
"sphinx.ext.viewcode",
37+
"sphinx_autodoc_typehints",
38+
]
39+
40+
# Add any paths that contain templates here, relative to this directory.
41+
templates_path = ["_templates"]
42+
exclude_patterns: list[str] = []
43+
44+
# The suffix(es) of source filenames.
45+
source_suffix = [".rst", ".md"]
46+
47+
# The master toctree document.
48+
master_doc = "index"
49+
50+
# The name of the Pygments (syntax highlighting) style to use.
51+
pygments_style = "sphinx"
52+
53+
autodoc_default_options = {
54+
"members": None,
55+
"undoc-members": None,
56+
"show-inheritance": None,
57+
}
58+
59+
# The theme to use for HTML and HTML Help pages.
60+
html_theme = "pydata_sphinx_theme"
61+
# html_logo = "_static/avatar.jpeg"
62+
html_favicon = "_static/avatar.jpeg"
63+
html_theme_options = {
64+
"github_url": "https://github.com/pyscript/pyscript-cli",
65+
"icon_links": [
66+
{
67+
"name": "PyPI",
68+
"url": "https://pypi.org/project/pyscript-cli",
69+
"icon": "fas fa-box",
70+
},
71+
],
72+
}
73+
html_static_path = ["_static"]

‎docs/source/index.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
```{include} ../../README.md
2+
```
3+
4+
```{toctree}
5+
:maxdepth: 3
6+
:caption: Contents
7+
8+
user_guide
9+
api/modules
10+
```

‎docs/source/user_guide.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# User Guide
2+
3+
## Developing a new plugin
4+
5+
Create a function, and then register it like below.
6+
7+
```python
8+
from pyscript import console, plugins
9+
10+
11+
def create():
12+
"""Creates a new PyScript Project from scratch."""
13+
console.print("pyscript create cmd not yet available..", style="bold green")
14+
return True
15+
16+
17+
@plugins.register
18+
def pyscript_subcommand():
19+
return create
20+
```

‎pyproject.toml

+17-1
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,31 @@ packages = [
2222
python = "^3.7"
2323
importlib-metadata = {version = "^4.11.3", python = "3.7"}
2424
Jinja2 = "^3.1.2"
25+
pluggy = "^1.0.0"
2526
rich = "^12.3.0"
2627
rich-click = {extras = ["typer"], version = "^1.3.0"}
28+
toml = "^0.10.2"
2729
typer = "^0.4.1"
28-
pluggy = "^1.0.0"
30+
Sphinx = {version = "^5.1.1", optional = true}
31+
sphinx-autobuild = {version = "^2021.3.14", optional = true}
32+
sphinx-autodoc-typehints = {version = "^1.19.2", optional = true}
33+
myst-parser = {version = "^0.18.0", optional = true}
34+
pydata-sphinx-theme = {version = "^0.9.0", optional = true}
2935

3036
[tool.poetry.dev-dependencies]
3137
coverage = "^6.3.2"
3238
mypy = "^0.950"
3339
pytest = "^7.1.2"
40+
types-toml = "^0.10.8"
41+
42+
[tool.poetry.extras]
43+
docs = [
44+
"sphinx",
45+
"sphinx-autobuild",
46+
"sphinx-autodoc-typehints",
47+
"myst-parser",
48+
"pydata-sphinx-theme",
49+
]
3450

3551
[tool.poetry.scripts]
3652
pyscript = "pyscript.cli:app"

0 commit comments

Comments
 (0)