Skip to content

Commit

Permalink
Merge branch 'main' into 64
Browse files Browse the repository at this point in the history
  • Loading branch information
sergiusens authored Oct 6, 2023
2 parents facc8cf + f3a04d1 commit 6b1c2b6
Show file tree
Hide file tree
Showing 16 changed files with 505 additions and 64 deletions.
49 changes: 49 additions & 0 deletions .github/workflows/automatic-doc-checks.yml
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"
1 change: 1 addition & 0 deletions .github/workflows/docs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ jobs:
uses: actions/checkout@v4
with:
fetch-depth: 0
submodules: recursive
- name: Setup Python
uses: actions/setup-python@v4
with:
Expand Down
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,11 @@ instance/

# Sphinx documentation
docs/_build/
docs/.sphinx/venv/
docs/.sphinx/warnings.txt
docs/.sphinx/.wordlist.dic
docs/.sphinx/.doctrees/
docs/sphinx-docs-starter-pack/*

# PyBuilder
target/
Expand Down
3 changes: 3 additions & 0 deletions .gitmodules
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
24 changes: 15 additions & 9 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,29 @@
# Required
version: 2

submodules:
include:
- docs/sphinx-docs-starter-pack

# Set the version of Python and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.11"

# Build documentation in the docs/ directory with Sphinx
sphinx:
builder: dirhtml
configuration: docs/conf.py
fail_on_warning: true

# Optionally build your docs in additional formats such as PDF
# If using Sphinx, optionally build your docs in additional formats such as PDF
formats:
- pdf
- epub

build:
os: ubuntu-22.04
tools:
python: "3"

# Optionally declare the Python requirements required to build your docs
python:
install:
- requirements: docs/.sphinx/requirements.txt
- method: pip
path: .
extra_requirements:
- docs
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
[![Documentation Status](https://readthedocs.com/projects/canonical-craft-store/badge/?version=latest)](https://canonical-craft-store.readthedocs-hosted.com/en/latest/?badge=latest)

# Craft Store

This project aims to provide python interfaces for communicating with
Expand All @@ -9,7 +11,7 @@ Free software: GNU Lesser General Public License v3

# Documentation:

https://craft-store.readthedocs.io.
https://canonical-craft-store.readthedocs-hosted.com.

# Contributing

Expand Down
17 changes: 17 additions & 0 deletions docs/.custom_wordlist.txt
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
14 changes: 14 additions & 0 deletions docs/.sphinx/requirements.txt
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
1 change: 1 addition & 0 deletions docs/.wordlist.txt
130 changes: 130 additions & 0 deletions docs/Makefile
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
Loading

0 comments on commit 6b1c2b6

Please sign in to comment.