Skip to content

Commit bd7f0f7

Browse files
joeldodsonjoeldodson
committed
docs now using sphinx, ready to improve docs. bumped version due to repackaging dicli
1 parent ddf87c2 commit bd7f0f7

File tree

14 files changed

+1066
-282
lines changed

14 files changed

+1066
-282
lines changed

‎.github/workflows/ci_mkdocs.yml‎

Lines changed: 0 additions & 25 deletions
This file was deleted.

‎.github/workflows/sphinx.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: sphinx to github pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
docs:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
- uses: actions/setup-python@v5
17+
with:
18+
python-version: 3.x
19+
- name: Install dependencies
20+
run: |
21+
pip install -r docs/requirements.txt
22+
- name: Sphinx build
23+
run: |
24+
sphinx-build docs _build
25+
- name: Deploy to GitHub Pages
26+
uses: peaceiris/actions-gh-pages@v4
27+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
28+
with:
29+
publish_branch: gh-pages
30+
github_token: ${{ secrets.GITHUB_TOKEN }}
31+
publish_dir: _build/
32+
force_orphan: true

‎docs/CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
# Changelog
22

3-
## v0.1.18 (2025-05-xx)
3+
## v0.1.18 (2025-05-21)
44

55
- changes to packaging and docs, nothing API related though
66
- upgraded to poetry 2.x
77

88
- no longer able to specify dicli script as an extra
99
without using deprecated functionality from poetry
10+
- so now it is always installed
1011

1112
- moved dicli to be in domible package and moved elements command out of dicli
1213

‎docs/CONTRIBUTING.md‎

Lines changed: 0 additions & 73 deletions
This file was deleted.

‎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/about.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# About
2+
3+
domible is an evolution of the
4+
[pymenable package](https://pypi.org/project/pymenable/)
5+
which is deprecated.
6+
7+
Instead of using jinja templates for the basic structure of the HTML document (as I did in pymenable),
8+
domible uses only Python classes to create and modify the HTML document.
9+
a root class, Html, generates the <html> element.
10+
Head and Body classes generate the <head> and <body> elements.
11+
Elements can be added to the head and body to generate HTML documents of arbitrary complexity.
12+
13+
I decided pymenable was too complicated using jinja templates
14+
(e.g., having to manage extra resources and learn to use jinja).
15+
16+
I'm not disparaging jinja, it's an awesome tool.
17+
I think it's easier though to use Python classes to create the root element as well as all the other elements for the HTML document.
18+
19+
Plus I wanted to change the name.
20+
21+
## Contributing?
22+
23+
If you're interested in being part of this rambling experiment,
24+
please open an issue in github to initiate a conversation.
25+
Please first take a quick read through the
26+
[Code of Conduct](CONDUCT.md).
27+
It's very short and casual.

‎docs/conf.py‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'Domible Documentation'
10+
copyright = '2025-%Y, Joel Dodson'
11+
author = 'Joel Dodson'
12+
version = '0.1'
13+
release = '0.1.0'
14+
needs_sphinx = '8.2'
15+
16+
# -- General configuration ---------------------------------------------------
17+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
18+
19+
extensions = ["myst_parser", "pydata_sphinx_theme"]
20+
21+
templates_path = ['_templates']
22+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
23+
24+
# -- Options for HTML output -------------------------------------------------
25+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
26+
27+
html_static_path = ["_static"]
28+
29+
# links for the sphinx_book_theme
30+
# the 'book' theme is based on the 'pydata' theme thus options derive from there as well.
31+
# pdata-sphinx-theme opsions: https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/layout.html#references
32+
# sphinx-book-theme options: https://sphinx-book-theme.readthedocs.io/en/latest/reference.html
33+
34+
html_title = 'Domible Documentation'
35+
html_last_updated_fmt = ""
36+
html_show_copyright = False
37+
html_show_sphinx = True
38+
html_show_sourcelink = False
39+
# remove all side bars, only have horizontal nav in header
40+
html_sidebars = {"**": []}
41+
html_theme = "pydata_sphinx_theme"
42+
html_theme_options = {
43+
"navbar_align": "left",
44+
"github_url": "https://github.com/joeldodson/webdevaccess",
45+
"content_footer_items": [],
46+
"footer_start": [],
47+
"footer_end": [],
48+
"footer_center": ["sphinx-version", "theme-version", "last-updated"],
49+
"show_version_warning_banner": False,
50+
# no secondary sidebars for any pages
51+
"secondary_sidebar_items": {"**": []},
52+
# trying to get rid of inaccessible color mode switcher
53+
"navbar_end": ["navbar-icon-links"],
54+
###
55+
# folowing are options (I think) only used by sphinx-book-theme
56+
# leaving them here in case I try that theme again
57+
## "use_download_button": False,
58+
## "repository_branch": "main",
59+
## "use_issues_button": True,
60+
## "use_repository_button": True,
61+
## "home_page_in_toc": True,
62+
## "footer_content_items": [],
63+
}
64+

‎docs/example.ipynb‎

Lines changed: 0 additions & 108 deletions
This file was deleted.

0 commit comments

Comments
 (0)