-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
documentation: Use Sphinx for building HTML documentation (#87)
* documentation: Use Sphinx for building HTML documentation
Backwards compatible; the only (minor) alteration to `boardwalk` -- which is the only reason this is getting a
version increment -- is invocations of `boardwalk` now only emit the current loglevel -- that is,
`Log level is {loglevel}`, at verbosity 1 or higher (e.g., `boardwalk -v ...`).
Implements Sphinx to have some HTML-based documentation, so referencing documentation that is
not directly in Python source code files is possible. While is not intended to fully document all available
functions with this change, this _does_ provide the necessary framework which
allows future documentation of the code -- within the code itself by way of docstrings -- to
auto-generate updated documentation.
This can be accomplished by running `make docs` from the root of the repository, or in the alternative,
running `make html` from the `docs/` directory (if in a `poetry shell` session). This directs Sphinx to
build the HTML documentation, which when complete is available at `docs/build/html/index.html`.- Loading branch information
1 parent
e9acd03
commit 9e39169
Showing
22 changed files
with
1,479 additions
and
288 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| # Please see the documentation for all configuration options: | ||
| # https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file | ||
|
|
||
| version: 2 | ||
| updates: | ||
| # To monitor pyproject.toml / Poetry.lock files | ||
| - package-ecosystem: "pip" | ||
| directory: "/" | ||
| schedule: | ||
| interval: "daily" | ||
| # For keeping workflows up-to-date. | ||
| - package-ecosystem: "github-actions" | ||
| directory: "/" | ||
| schedule: | ||
| interval: "daily" | ||
| labels: | ||
| - "CI/CD" | ||
| commit-message: | ||
| prefix: ci |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| # Dummy file to let help be generated... | ||
| # TODO: Figure out how to let things like the below work without erroring; it should "just work" | ||
| # | ||
| # rich-click --output html boardwalk workspace --help | ||
| # 2024-10-31 16:33:18.521 | INFO | boardwalk.cli:cli:77 - Log level is INFO | ||
|
|
||
| # ╭─ Error ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ | ||
| # │ No Boardwalkfile.py found │ | ||
| # ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ | ||
| # (boardwalk-py3.12) asullivan@MBP-NT9RPG2XV7 boardwalk % |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| # Minimal makefile for Sphinx documentation | ||
| # | ||
|
|
||
| # You can set these variables from the command line, and also | ||
| # from the environment for the first two. | ||
| SPHINXOPTS ?= | ||
| SPHINXBUILD ?= sphinx-build | ||
| SOURCEDIR = source | ||
| BUILDDIR = build | ||
|
|
||
| # Put it first so that "make" without argument is like "make help". | ||
| .PHONY: help Makefile | ||
| help: | ||
| @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
|
||
| # Define some build targets manually, since we also have the auto-generated documentation to handle | ||
| .PHONY: clean | ||
| clean: | ||
| @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
| -rm -r source/_autogenerated | ||
|
|
||
| .PHONY: generate_cli_help_page_sources | ||
| generate_cli_help_page_sources: | ||
| ./build_cli_help_pages.sh | ||
|
|
||
| .PHONY: html | ||
| html: generate_cli_help_page_sources | ||
| @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
|
||
| # Catch-all target: route all unknown targets to Sphinx using the new | ||
| # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
| %: Makefile | ||
| @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
|
||
| livehtml: generate_cli_help_page_sources | ||
| sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| #!/bin/bash | ||
|
|
||
| # TODO / Possibility: Integrate rich-click into boardwalk/boardwalkd directly, | ||
| # so this workaround isn't needed to generate a pretty help text. | ||
|
|
||
| commands=( | ||
| "boardwalk" | ||
| "boardwalk catch" | ||
| "boardwalk check" | ||
| "boardwalk init" | ||
| "boardwalk login" | ||
| "boardwalk release" | ||
| "boardwalk run" | ||
| "boardwalk version" | ||
| "boardwalk workspace" | ||
| "boardwalk workspace dump" | ||
| "boardwalk workspace list" | ||
| "boardwalk workspace reset" | ||
| "boardwalk workspace show" | ||
| "boardwalk workspace use" | ||
|
|
||
| "boardwalkd" | ||
| "boardwalkd serve" | ||
| "boardwalkd version" | ||
| ) | ||
|
|
||
| OUTPUT_WIDTH_COLUMMNS=110 | ||
|
|
||
| GET_PAGE_NAME() { | ||
| echo '`'"$1"'`' | ||
| } | ||
|
|
||
| AUTO_GEN_DIR=source/_autogenerated/cli_helpdocs | ||
| mkdir -p "$AUTO_GEN_DIR" | ||
| mkdir -p "$AUTO_GEN_DIR/boardwalk" | ||
| mkdir -p "$AUTO_GEN_DIR/boardwalkd" | ||
|
|
||
| for cmd in "${commands[@]}"; do | ||
| # Define regular expression patterns for 'boardwalk' and 'boardwalkd', so we | ||
| # can sort them into the correct subdirectories. Note that we need to use | ||
| # POSIX-compliant EREs, here, since this is portable between MacOS/Linux. | ||
| # See: https://stackoverflow.com/a/12696899 | ||
| # This is, effectively, '\bboardwalk\b' and '\bboardwalkd\b' | ||
| BOARDWALK_REGEX="^[[:<:]]boardwalk[[:>:]]" | ||
| BOARDWALKD_REGEX="^[[:<:]]boardwalkd[[:>:]]" | ||
| if [[ $cmd =~ $BOARDWALK_REGEX ]]; then | ||
| SUBDIR=boardwalk | ||
| elif [[ $cmd =~ $BOARDWALKD_REGEX ]]; then | ||
| SUBDIR=boardwalkd | ||
| else | ||
| # Don't assume if we cannot correctly parse the command being generated | ||
| echo "[!] Skipping generation for $cmd; is this a boardwalk or boardwalkd command?" | ||
| continue | ||
| fi | ||
| FILENAME=$AUTO_GEN_DIR/$SUBDIR/$(echo "$cmd" | tr ' ' _).md | ||
| echo "[+] Generating doc page for $cmd" | ||
| touch "$FILENAME" | ||
| { | ||
| echo "# $(GET_PAGE_NAME "$cmd")" | ||
| echo "" | ||
| echo '<div class="full-width" id="cmd-help-text">' | ||
| echo '<pre>' | ||
| # shellcheck disable=SC2086 # We actually want word splitting, here | ||
| COLUMNS=$OUTPUT_WIDTH_COLUMMNS rich-click --output html $cmd --help | ||
| echo '</pre>' | ||
| echo '</div>' | ||
| echo '' | ||
| } > "$FILENAME" | ||
| done |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| ../../../diagrams |
Oops, something went wrong.