Skip to content

Commit 48a8742

Browse files
jmgatejmgate
authored
Merge pull request #17 from sandialabs/add-docs
Stub out Sphinx documentation
2 parents 810d6fb + 40f08f2 commit 48a8742

12 files changed

+236
-0
lines changed

‎.github/workflows/continuous-integration.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ jobs:
3333
python3 -m pip install --upgrade pip
3434
python3 -m pip install \
3535
-r requirements.txt \
36+
-r doc/requirements.txt \
3637
-r test/requirements.txt
3738
3839
- name: Test install

‎.readthedocs.yaml

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Read the Docs configuration file for Sphinx projects.
2+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for
3+
# details.
4+
5+
# Required.
6+
version: 2
7+
8+
# Set the OS, Python version, and other tools you need.
9+
build:
10+
os: "ubuntu-22.04"
11+
tools:
12+
python: "3.12"
13+
14+
# Build documentation in the "doc/" directory with Sphinx.
15+
sphinx:
16+
fail_on_warning: true
17+
configuration: doc/source/conf.py
18+
19+
# Declare Python requirements for building the documentation.
20+
python:
21+
install:
22+
- method: pip
23+
path: .
24+
- requirements: requirements.txt
25+
- requirements: doc/requirements.txt

‎doc/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
build

‎doc/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 = source
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)

‎doc/make-html.bash

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/usr/bin/env bash
2+
ORIG_DIR=$(pwd)
3+
SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &> /dev/null && pwd)
4+
cd "${SCRIPT_DIR}" || exit 1
5+
make clean
6+
python3 -m pip uninstall -y staged-script
7+
cd ..
8+
python3 -m pip install .
9+
cd "${SCRIPT_DIR}" || exit 1
10+
make html
11+
cd "${ORIG_DIR}" || exit 1

‎doc/requirements.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Requirements for building the `staged-script` documentation.
2+
3+
sphinx
4+
sphinx-autodoc-typehints
5+
sphinx-copybutton
6+
sphinx-rtd-theme
7+
sphinxcontrib-programoutput

‎doc/source/_static/.gitkeep

Whitespace-only changes.

‎doc/source/conf.py

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
"""
2+
Configuration file for the Sphinx documentation builder.
3+
4+
For the full list of built-in configuration values, see the documentation:
5+
https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
"""
7+
8+
import sys
9+
from pathlib import Path
10+
11+
sys.path.append(str(Path.cwd().parents[2].resolve() / "staged_script"))
12+
13+
# -- Project information ------------------------------------------------------
14+
15+
project = "staged-script"
16+
copyright = ( # noqa: A001
17+
"2024, National Technology & Engineering Solutions of Sandia, LLC (NTESS)"
18+
)
19+
author = "Jason M. Gates"
20+
version = "1.0.0"
21+
release = version
22+
23+
# -- General configuration ----------------------------------------------------
24+
25+
extensions = [
26+
"sphinx.ext.autodoc",
27+
"sphinx.ext.coverage",
28+
"sphinx.ext.intersphinx",
29+
"sphinx.ext.napoleon",
30+
"sphinx.ext.viewcode",
31+
"sphinx_autodoc_typehints",
32+
"sphinx_copybutton",
33+
"sphinx_rtd_theme",
34+
"sphinxcontrib.programoutput",
35+
]
36+
intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
37+
38+
templates_path = ["_templates"]
39+
40+
41+
# -- Options for HTML output --------------------------------------------------
42+
43+
html_theme = "sphinx_rtd_theme"
44+
html_static_path = ["_static"]
45+
46+
# -- AutoDoc Configuration ----------------------------------------------------
47+
48+
autodoc_default_options = {
49+
"show-inheritance": True,
50+
"members": True,
51+
"undoc-members": True,
52+
}
53+
autoclass_content = "both"
54+
autodoc_preserve_defaults = True
55+
autodoc_inherit_docstrings = False

‎doc/source/examples.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Examples
2+
========

‎doc/source/index.rst

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
staged-script
2+
=============
3+
4+
.. toctree::
5+
:hidden:
6+
:maxdepth: 2
7+
:caption: Contents
8+
9+
motivation
10+
examples
11+
reference
12+
13+
|Code lines|
14+
|codecov|
15+
|CodeFactor|
16+
|CodeQL|
17+
|conda-forge Version|
18+
|conda-forge Downloads|
19+
|Continuous Integration|
20+
|Contributor Covenant|
21+
|GitHub Contributors|
22+
|Documentation Status|
23+
|License|
24+
|Merged PRs|
25+
|OpenSSF Best Practices|
26+
|OpenSSF Scorecard|
27+
|Platforms|
28+
|pre-commit|
29+
|pre-commit.ci Status|
30+
|PyPI Version|
31+
|PyPI Downloads|
32+
|Python Version|
33+
|Ruff|
34+
35+
.. |Code lines| image:: https://sloc.xyz/github/sandialabs/staged-script/?category=code
36+
.. |codecov| image:: https://codecov.io/gh/sandialabs/staged-script/branch/master/graph/badge.svg?token=FmDStZ6FVR
37+
:target: https://codecov.io/gh/sandialabs/staged-script
38+
.. |CodeFactor| image:: https://www.codefactor.io/repository/github/sandialabs/staged-script/badge/master
39+
:target: https://www.codefactor.io/repository/github/sandialabs/staged-script/overview/master
40+
.. |CodeQL| image:: https://github.com/sandialabs/staged-script/actions/workflows/github-code-scanning/codeql/badge.svg
41+
:target: https://github.com/sandialabs/staged-script/actions/workflows/github-code-scanning/codeql
42+
.. |conda-forge Version| image:: https://img.shields.io/conda/v/conda-forge/staged-script?label=conda-forge
43+
:target: https://anaconda.org/conda-forge/staged-script
44+
.. |conda-forge Downloads| image:: https://img.shields.io/conda/d/conda-forge/staged-script?label=conda-forge%20downloads
45+
.. |Continuous Integration| image:: https://github.com/sandialabs/staged-script/actions/workflows/continuous-integration.yml/badge.svg
46+
:target: https://github.com/sandialabs/staged-script/actions/workflows/continuous-integration.yml
47+
.. |Contributor Covenant| image:: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
48+
:target: https://github.com/sandialabs/staged-script/blob/master/CODE_OF_CONDUCT.md
49+
.. |GitHub Contributors| image:: https://img.shields.io/github/contributors/sandialabs/staged-script.svg
50+
:target: https://github.com/sandialabs/staged-script/graphs/contributors
51+
.. |Documentation Status| image:: https://readthedocs.org/projects/staged-script/badge/?version=latest
52+
:target: https://staged-script.readthedocs.io/en/latest/?badge=latest
53+
.. |License| image:: https://anaconda.org/conda-forge/staged-script/badges/license.svg
54+
:target: https://github.com/sandialabs/staged-script/blob/master/LICENSE.md
55+
.. |Merged PRs| image:: https://img.shields.io/github/issues-pr-closed-raw/sandialabs/staged-script.svg?label=merged+PRs
56+
:target: https://github.com/sandialabs/staged-script/pulls?q=is:pr+is:merged
57+
.. |OpenSSF Best Practices| image:: https://bestpractices.coreinfrastructure.org/projects/8864/badge
58+
:target: https://bestpractices.coreinfrastructure.org/projects/8864
59+
.. |OpenSSF Scorecard| image:: https://api.securityscorecards.dev/projects/github.com/sandialabs/staged-script/badge
60+
:target: https://securityscorecards.dev/viewer/?uri=github.com/sandialabs/staged-script
61+
.. |Platforms| image:: https://anaconda.org/conda-forge/staged-script/badges/platforms.svg
62+
.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit
63+
:target: https://github.com/pre-commit/pre-commit
64+
.. |pre-commit.ci Status| image:: https://results.pre-commit.ci/badge/github/sandialabs/staged-script/master.svg
65+
:target: https://results.pre-commit.ci/latest/github/sandialabs/staged-script/master
66+
.. |PyPI Version| image:: https://img.shields.io/pypi/v/staged-script?label=PyPI
67+
:target: https://pypi.org/project/staged-script/
68+
.. |PyPI Downloads| image:: https://img.shields.io/pypi/dm/staged-script?label=PyPI%20downloads
69+
.. |Python Version| image:: https://img.shields.io/badge/Python-3.8|3.9|3.10|3.11|3.12-blue.svg
70+
.. |Ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
71+
:target: https://github.com/astral-sh/ruff
72+
73+
INSERT INTRODUCTION HERE.
74+
75+
Installation
76+
------------
77+
78+
To get up and running with ``staged-script``, simply
79+
80+
.. code-block:: bash
81+
82+
python3 -m pip install staged-script
83+
84+
Usage
85+
-----
86+
87+
Once the package is installed, you can simply
88+
89+
.. code-block:: python
90+
91+
from staged_script import StagedScript
92+
93+
class MyScript(StagedScript):
94+
@StagedScript.stage("greet")
95+
def say_hello(self) -> None:
96+
print("Hello world")
97+
98+
# COMPLETE THIS EXAMPLE.
99+
100+
For more detailed usage information, see the :doc:`examples` page. For
101+
implementation details, see the :doc:`reference documentation <reference>`.
102+
103+
Contributing
104+
------------
105+
106+
The source repository for this module is `on GitHub`_. See the project's
107+
README and contributing guidelines for details on how to interact with the
108+
project.
109+
110+
.. _on GitHub: https://github.com/sandialabs/staged-script

‎doc/source/motivation.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Motivation
2+
==========

‎doc/source/reference.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Reference
2+
=========

0 commit comments

Comments
 (0)