-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(docs): use canonical starter pack
- Loading branch information
Showing
15 changed files
with
502 additions
and
63 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,49 @@ | ||
name: Main Documentation Checks | ||
|
||
on: | ||
- push | ||
- pull_request | ||
- workflow_dispatch | ||
|
||
concurrency: | ||
group: ${{ github.workflow }}-${{ github.ref }} | ||
cancel-in-progress: true | ||
|
||
jobs: | ||
docchecks: | ||
name: Run documentation checks | ||
runs-on: ubuntu-latest | ||
outputs: | ||
result_spelling: ${{ steps.spellcheck-step.outcome }} | ||
result_woke: ${{ steps.woke-step.outcome }} | ||
result_links: ${{ steps.linkcheck-step.outcome }} | ||
steps: | ||
- name: Checkout | ||
uses: actions/checkout@v3 | ||
with: | ||
submodules: recursive | ||
|
||
- name: Remove upstream unused files | ||
run: | | ||
rm -f docs/sphinx-docs-starter-pack/doc-cheat-sheet* | ||
- name: Spell Check | ||
id: spellcheck-step | ||
if: success() || failure() | ||
uses: canonical/documentation-workflows/spellcheck@main | ||
with: | ||
working-directory: "docs" | ||
|
||
- name: Inclusive Language Check | ||
id: woke-step | ||
if: success() || failure() | ||
uses: canonical/documentation-workflows/inclusive-language@main | ||
with: | ||
working-directory: "docs" | ||
|
||
- name: Link Check | ||
id: linkcheck-step | ||
if: success() || failure() | ||
uses: canonical/documentation-workflows/linkcheck@main | ||
with: | ||
working-directory: "docs" |
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,3 @@ | ||
[submodule "docs/sphinx-docs-starter-pack"] | ||
path = docs/sphinx-docs-starter-pack | ||
url = https://github.com/canonical/sphinx-docs-starter-pack.git |
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,17 @@ | ||
Changelog | ||
cli | ||
datetime | ||
http | ||
https | ||
io | ||
initialization | ||
initialized | ||
NotLoggedIn | ||
keyring | ||
StoreClient | ||
snapcraft | ||
SSO | ||
ubuntu | ||
unregistering | ||
url | ||
whoami |
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,14 @@ | ||
furo==2023.9.10 | ||
lxd-sphinx-extensions==0.0.14 | ||
myst-parser==2.0.0 | ||
pyspelling==2.9 | ||
sphinx==7.2.6 | ||
sphinx-autobuild==2021.3.14 | ||
sphinxcontrib-jquery==4.1 | ||
sphinx-copybutton==0.5.2 | ||
sphinx-design==0.5.0 | ||
sphinxext-opengraph==0.8.2 | ||
sphinx-lint==0.6.8 | ||
sphinx-notfound-page==1.0.0 | ||
sphinx-reredirects==0.1.2 | ||
sphinx-tabs==3.4.1 |
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 @@ | ||
sphinx-docs-starter-pack/.wordlist.txt |
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,130 @@ | ||
# Minimal makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line, and also | ||
# from the environment for the first two. | ||
SPHINXOPTS ?= -c . -d .sphinx/.doctrees | ||
SPHINXBUILD ?= sphinx-build | ||
SPHINXDIR = .sphinx | ||
SOURCEDIR = . | ||
BUILDDIR = _build | ||
VENVDIR = $(SPHINXDIR)/venv | ||
VENV = $(VENVDIR)/bin/activate | ||
|
||
|
||
# Put it first so that "make" without argument is like "make help". | ||
help: | ||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
||
.PHONY: help | ||
|
||
# Explicit target avoids fall-through to the "Makefile" target. | ||
$(SPHINXDIR)/requirements.txt: | ||
test -f $(SPHINXDIR)/requirements.txt | ||
|
||
# If requirements are updated, venv should be rebuilt and timestamped. | ||
$(VENVDIR): $(SPHINXDIR)/requirements.txt | ||
@echo "... setting up virtualenv" | ||
python3 -m venv $(VENVDIR) | ||
. $(VENV); pip install --require-virtualenv \ | ||
--upgrade -r $(SPHINXDIR)/requirements.txt \ | ||
--log $(VENVDIR)/pip_install.log | ||
@test ! -f $(VENVDIR)/pip_list.txt || \ | ||
mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak | ||
@. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt | ||
@echo "\n" \ | ||
"--------------------------------------------------------------- \n" \ | ||
"* watch, build and serve the documentation: make run \n" \ | ||
"* only build: make html \n" \ | ||
"* only serve: make serve \n" \ | ||
"* clean built doc files: make clean-doc \n" \ | ||
"* clean full environment: make clean \n" \ | ||
"* check spelling: make spelling \n" \ | ||
"* check inclusive language: make woke \n" \ | ||
"* other possible targets: make <press TAB twice> \n" \ | ||
"--------------------------------------------------------------- \n" | ||
@touch $(VENVDIR) | ||
|
||
|
||
woke-install: | ||
@type woke >/dev/null 2>&1 || \ | ||
{ echo "Installing \"woke\" snap... \n"; sudo snap install woke; } | ||
|
||
.PHONY: woke-install | ||
|
||
|
||
install: $(VENVDIR) woke-install | ||
|
||
.PHONY: install | ||
|
||
|
||
run: install | ||
. $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" \ | ||
$(SPHINXOPTS) | ||
|
||
.PHONY: run | ||
|
||
# Doesn't depend on $(BUILDDIR) to rebuild properly at every run. | ||
html: install | ||
. $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" \ | ||
-w .sphinx/warnings.txt $(SPHINXOPTS) | ||
|
||
.PHONY: html | ||
|
||
|
||
epub: install | ||
. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" \ | ||
-w .sphinx/warnings.txt $(SPHINXOPTS) | ||
|
||
.PHONY: epub | ||
|
||
|
||
serve: html | ||
cd "$(BUILDDIR)"; python3 -m http.server 8000 | ||
|
||
.PHONY: serve | ||
|
||
|
||
clean: clean-doc | ||
@test ! -e "$(VENVDIR)" -o \ | ||
-d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" | ||
rm -rf $(VENVDIR) | ||
rm -rf .sphinx/.doctrees | ||
|
||
.PHONY: clean | ||
|
||
|
||
clean-doc: | ||
git clean -fx "$(BUILDDIR)" | ||
|
||
.PHONY: clean-doc | ||
|
||
|
||
spelling: html | ||
. $(VENV) ; python3 -m pyspelling -c sphinx-docs-starter-pack/.sphinx/spellingcheck.yaml | ||
|
||
.PHONY: spelling | ||
|
||
|
||
linkcheck: install | ||
. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" \ | ||
$(SPHINXOPTS) | ||
|
||
.PHONY: linkcheck | ||
|
||
|
||
woke: woke-install | ||
woke *.rst **/*.rst \ | ||
--exit-1-on-failure \ | ||
-c https://github.com/canonical/Inclusive-naming/raw/main/config.yml | ||
|
||
.PHONY: woke | ||
|
||
|
||
# Catch-all target: route all unknown targets to Sphinx using the new | ||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
%: Makefile | ||
. $(VENV); \ | ||
$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
||
.PHONY: Makefile |
Oops, something went wrong.