Skip to content

Commit 8f0a0c6

Browse files
SimonBlankeSimonBlanke
committed
[DOC] add docs generation skeleton
1 parent 87e670a commit 8f0a0c6

33 files changed

Lines changed: 1236 additions & 1 deletion

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,6 @@ MANIFEST
3232
# before PyInstaller builds the exe, so as to inject date/other infos into it.
3333
*.manifest
3434
*.spec
35-
requirements*.txt
3635

3736
# Installer logs
3837
pip-log.txt
@@ -75,6 +74,8 @@ instance/
7574

7675
# Sphinx documentation
7776
docs/_build/
77+
docs/build/
78+
docs/source/api_reference/auto_generated/
7879

7980
# PyBuilder
8081
target/

‎docs/README.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Hyperactive Documentation
2+
3+
This directory contains the Sphinx-based documentation for Hyperactive.
4+
5+
## Building the Documentation
6+
7+
### Prerequisites
8+
9+
Install the required dependencies:
10+
11+
```bash
12+
pip install -r requirements.txt
13+
```
14+
15+
You'll also need to have Hyperactive installed:
16+
17+
```bash
18+
pip install -e .. # Install Hyperactive in development mode from parent directory
19+
```
20+
21+
### Building HTML Documentation
22+
23+
From the `source` directory:
24+
25+
```bash
26+
cd source
27+
make clean # Clean previous builds
28+
make html # Build HTML documentation
29+
```
30+
31+
The built documentation will be in `build/html/`. Open `build/html/index.html` in your browser to view.
32+
33+
### Live Preview with Auto-Rebuild
34+
35+
For development, you can use auto-rebuild mode:
36+
37+
```bash
38+
cd source
39+
make autobuild
40+
```
41+
42+
This will start a local server (typically at http://127.0.0.1:8000) that automatically rebuilds when you make changes to the documentation source files.
43+
44+
## Documentation Structure
45+
46+
- `source/` - Documentation source files
47+
- `conf.py` - Sphinx configuration
48+
- `index.rst` - Main landing page
49+
- `api_reference/` - API reference documentation (auto-generated)
50+
- `user_guide/` - User guide pages (currently stubs)
51+
- `examples/` - Example notebooks and galleries (currently stubs)
52+
- `get_involved/` - Contributing guidelines (currently stubs)
53+
- `about/` - About pages (currently stubs)
54+
- `_templates/` - Custom Sphinx templates
55+
- `_static/` - Static files (CSS, images, etc.)
56+
- `build/` - Built documentation (generated, not tracked in git)
57+
58+
## Current Status
59+
60+
The documentation is currently set up with:
61+
62+
- ✅ Full API reference auto-generated from docstrings
63+
- ✅ Sphinx configuration following SK-Time's approach
64+
- ✅ pydata_sphinx_theme for consistent look with scientific Python ecosystem
65+
- ✅ Structural placeholders for future static content
66+
67+
Static pages (User Guide, Examples, etc.) are currently placeholder stubs marked "under construction" that can be filled in later.
68+
69+
## Adding New Content
70+
71+
### API Reference
72+
73+
The API reference is automatically generated from docstrings. To update:
74+
75+
1. Ensure your class/function has proper NumPy-style docstrings
76+
2. Add the class/function to the appropriate `api_reference/*.rst` file using the `autosummary` directive
77+
3. Rebuild the documentation
78+
79+
### Static Pages
80+
81+
To add content to the placeholder pages:
82+
83+
1. Edit the corresponding `.rst` or `.md` file in the appropriate directory
84+
2. Remove the "under construction" note
85+
3. Add your content using reStructuredText or Markdown syntax
86+
4. Rebuild to see your changes
87+
88+
## Notes
89+
90+
- All API documentation is 100% auto-generated from source code docstrings
91+
- The structure allows for easy addition of static content in the future
92+
- Build warnings about missing references are normal during early development

‎docs/requirements.txt‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Requirements for building Hyperactive documentation
2+
3+
# Core Sphinx and extensions
4+
sphinx>=7.0.0
5+
sphinx-autobuild
6+
sphinx-copybutton
7+
sphinx-design
8+
sphinx-issues
9+
myst-parser
10+
numpydoc
11+
12+
# Theme
13+
pydata-sphinx-theme
14+
15+
# For intersphinx linking
16+
# These need to be importable to build docs
17+
numpy
18+
pandas
19+
scikit-learn

‎docs/source/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+
# You can set these variables from the command line.
4+
SPHINXBUILD = sphinx-build
5+
SPHINXOPTS = -j auto
6+
SPHINXAUTOBUILD = sphinx-autobuild
7+
SPHINXAUTOOPTS = -j auto
8+
SOURCEDIR = .
9+
BUILDDIR = ../build
10+
HYPERACTIVEDIR = ../../src/hyperactive
11+
12+
.PHONY: help build autobuild
13+
14+
# "make" without argument is like "make help".
15+
help:
16+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)"
17+
18+
clean:
19+
rm -rf $(BUILDDIR)
20+
rm -rf api_reference/auto_generated
21+
@echo "Deleted directory $(BUILDDIR) and auto_generated files."
22+
23+
# $(O) is meant as a shortcut for custom options.
24+
# i.e to log stderr into a separate file:
25+
# make build O="--no-color 2> build_warnings.log"
26+
html:
27+
$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
28+
29+
# $(O) is meant as a shortcut for custom options.
30+
autobuild:
31+
$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" -d "$(BUILDDIR)/doctrees" $(SPHINXAUTOOPTS) $(O) --watch "$(HYPERACTIVEDIR)" --re-ignore ".*\.json"

‎docs/source/_static/css/custom.css‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/* Custom CSS for Hyperactive documentation */
2+
3+
/* Add any custom styling here */

‎docs/source/_static/fields.css‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
/* CSS for parameter fields and other structured documentation elements */
2+
3+
/* Styling for parameter lists */
4+
dl.field-list {
5+
display: grid;
6+
grid-template-columns: fit-content(30%) auto;
7+
}
8+
9+
dl.field-list > dt {
10+
font-weight: bold;
11+
word-break: break-word;
12+
padding-left: 0.5em;
13+
padding-right: 0.5em;
14+
}
15+
16+
dl.field-list > dd {
17+
padding-left: 0.5em;
18+
margin-top: 0em;
19+
margin-bottom: 0.5em;
20+
margin-left: 0em;
21+
}

‎docs/source/_templates/class.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{{objname}}
2+
{{ underline }}==============
3+
4+
.. currentmodule:: {{ module }}
5+
6+
.. autoclass:: {{ objname }}
7+
8+
.. include:: {{module}}.{{objname}}.examples
9+
10+
.. raw:: html
11+
12+
<div class="clearer"></div>

‎docs/source/_templates/function.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{{objname}}
2+
{{ underline }}====================
3+
4+
.. currentmodule:: {{ module }}
5+
6+
.. autofunction:: {{ objname }}
7+
8+
.. include:: {{module}}.{{objname}}.examples
9+
10+
.. raw:: html
11+
12+
<div class="clearer"></div>

‎docs/source/about.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. _about:
2+
3+
=====
4+
About
5+
=====
6+
7+
.. note::
8+
9+
This page is under construction. Content will be added in the future.
10+
11+
.. toctree::
12+
:maxdepth: 1
13+
14+
about/team
15+
about/history
16+
about/license
17+
18+
About Hyperactive
19+
-----------------
20+
21+
*Coming soon: Information about the Hyperactive project.*

‎docs/source/about/history.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. _history:
2+
3+
=======
4+
History
5+
=======
6+
7+
.. note::
8+
9+
This page is under construction. Content will be added in the future.
10+
11+
Project History
12+
---------------
13+
14+
*Coming soon: The history and evolution of Hyperactive.*

0 commit comments

Comments
 (0)