[Docs] Remove /src dir (canonical#1018)

.github/workflows/markdown.yaml

@@ -18,10 +18,10 @@ jobs:
           files: |
             docs/**/*.md
           files_ignore: |
-            docs/src/_parts/**
+            docs/canonicalk8s/_parts/**
       - uses: DavidAnson/markdownlint-cli2-action@v16
         if: steps.changed-markdown-files.outputs.any_changed == 'true'
         with:
-          config: "docs/src/.markdownlint.json"
+          config: "docs/canonicalk8s/.sphinx/.markdownlint.json"
           globs: ${{ steps.changed-markdown-files.outputs.all_changed_files }}
           separator: ","

.gitignore

@@ -15,11 +15,11 @@ k8s_*.txt
 
 # ignore docs ephemerals
 
-/docs/_build
-/docs/tools/.sphinx/venv/
-/docs/tools/.sphinx/warnings.txt
-/docs/tools/.sphinx/.wordlist.dic
-/docs/tools/.sphinx/.doctrees/
-/docs/tools/.sphinx/node_modules
-/docs/tools/.sphinx/styles/*
-/docs/tools/.sphinx/vale.ini
+/docs/canonicalk8s/_build
+/docs/canonicalk8s/.sphinx/venv/
+/docs/canonicalk8s/.sphinx/warnings.txt
+/docs/canonicalk8s/.sphinx/.wordlist.dic
+/docs/canonicalk8s/.sphinx/.doctrees/
+/docs/canonicalk8s/.sphinx/node_modules
+/docs/canonicalk8s/.sphinx/styles/*
+/docs/canonicalk8s/.sphinx/vale.ini

CONTRIBUTING.md

@@ -2,4 +2,4 @@
 
 Thanks for your interest in contributing to Canonical Kubernetes!
 
-Our contribution guide is hosted here: <https://documentation.ubuntu.com/canonical-kubernetes/latest/src/snap/howto/contribute/>
+Our contribution guide is hosted here: <https://documentation.ubuntu.com/canonical-kubernetes/latest/snap/howto/contribute/>

docs/README.md

@@ -7,15 +7,15 @@ The directories are organised like this:
 
 ```
 
-├── _build
-│   ├── {contains the generated docs}
 ├── README.md
-├── src
-│   ├──{source files for the docs}
 ├── canonicalk8s
+│   ├── _build
+│   │   ├── {contains the generated docs}
 │   ├──{sphinx build tools for creating the docs for Canonical K8s}
+│   ├──{source files for canonicalk8s docs}
 ├── moonray
 │   ├──{sphinx build tools for creating the docs for Canonical K8s}
+│   ├──{source files for moonray docs}
 ```
 
 ## Building the docs

docs/canonicalk8s/.readthedocs.yaml

@@ -24,11 +24,11 @@ build:
           exit 183;
         fi
         ls
-      
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   builder: dirhtml
-  configuration: docs/canonicalk8s/conf-rtd.py
+  configuration: docs/canonicalk8s/conf.py
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
 # formats:
@@ -38,6 +38,3 @@ sphinx:
 python:
    install:
    - requirements: docs/canonicalk8s/.sphinx/requirements.txt
-
-
-

docs/canonicalk8s/.sphinx/spellingcheck.yaml

@@ -1,30 +1,30 @@
 matrix:
-- name: rST files
-  aspell:
-    lang: en
-    d: en_GB
-  dictionary:
-    wordlists:
-    - src/.wordlist.txt
-    - src/.custom_wordlist.txt
-    output: .sphinx/.wordlist.dic
-  sources:
-  - ../_build/**/*.html
-  pipeline:
-  - pyspelling.filters.html:
-      comments: false
-      attributes:
-      - title
-      - alt
-      ignores:
-      - code
-      - pre
-      - spellexception
-      - link
-      - title
-      - div.relatedlinks
-      - strong.command
-      - div.visually-hidden
-      - img
-      - a.p-navigation__link
-      - a.contributor
+  - name: rST files
+    aspell:
+      lang: en
+      d: en_GB
+    dictionary:
+      wordlists:
+        - .sphinx/.wordlist.txt
+        - .custom_wordlist.txt
+      output: .sphinx/.wordlist.dic
+    sources:
+      - _build/**/*.html
+    pipeline:
+      - pyspelling.filters.html:
+          comments: false
+          attributes:
+            - title
+            - alt
+          ignores:
+            - code
+            - pre
+            - spellexception
+            - link
+            - title
+            - div.relatedlinks
+            - strong.command
+            - div.visually-hidden
+            - img
+            - a.p-navigation__link
+            - a.contributor

docs/canonicalk8s/Makefile

@@ -1,11 +1,23 @@
-# This Makefile stub allows you to customize starter pack (SP) targets.
-# Consider this file as a bridge between your project
-# and the starter pack's predefined targets that reside in Makefile.sp.
+# Minimal makefile for Sphinx documentation
 #
-# You can add your own, non-SP targets here or override SP targets
-# to fit your project's needs. For example, you can define and use targets
-# named "install" or "run", but continue to use SP targets like "sp-install"
-# or "sp-run" when working on the documentation.
+# Add your customisation to `Makefile` instead.
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXDIR     = .sphinx
+SPHINXOPTS    ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+METRICSDIR    = $(SOURCEDIR)/.sphinx/metrics
+BUILDDIR      = _build
+VENVDIR       = $(SPHINXDIR)/venv
+PA11Y         = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
+VENV          = $(VENVDIR)/bin/activate
+TARGET        = *
+ALLFILES      =  *.rst **/*.rst
+ADDPREREQS    ?=
+REQPDFPACKS   = latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng
+CONFIRM_SUDO    ?= N
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -27,5 +39,151 @@ help:
         "* other possible targets:                    make <TAB twice> \n" \
         "------------------------------------------------------------- \n"
 
+.PHONY: full-help woke-install spellcheck-install pa11y-install install run html \
+        epub serve clean clean-doc spelling spellcheck linkcheck woke \
+        allmetrics pa11y pdf-prep-force pdf-prep pdf Makefile.sp vale bash
+
+full-help: $(VENVDIR)
+	@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
+	@echo "Run 'make help' to see supported targets."
+
+# If requirements are updated, venv should be rebuilt and timestamped.
+$(VENVDIR):
+	python3 -c "import venv" || \
+        (echo "You must install python3-venv before you can build the documentation."; exit 1)
+	@echo "... setting up virtualenv"
+	python3 -m venv $(VENVDIR)
+	. $(VENV); pip install $(PIPOPTS) --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
+	@touch $(VENVDIR)
+
+woke-install:
+	@type woke >/dev/null 2>&1 || \
+	{ \
+		echo "Installing system-wide \"woke\" snap..."; \
+		confirm_sudo=$(CONFIRM_SUDO); \
+		if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \
+			read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \
+		fi; \
+		if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \
+			sudo snap install woke; \
+		else \
+			echo "Installation cancelled."; \
+		fi \
+	}
+
+	spellcheck-install:
+	@type aspell >/dev/null 2>&1 || \
+	{ \
+		echo "Installing system-wide \"aspell\" packages..."; \
+		confirm_sudo=$(CONFIRM_SUDO); \
+		if [ "$$confirm_sudo" != "y" ] && [ "$$confirm_sudo" != "Y" ]; then \
+			read -p "This requires sudo privileges. Proceed? [y/N]: " confirm_sudo; \
+		fi; \
+		if [ "$$confirm_sudo" = "y" ] || [ "$$confirm_sudo" = "Y" ]; then \
+			sudo apt-get install aspell aspell-en; \
+		else \
+			echo "Installation cancelled."; \
+		fi \
+	}
+pa11y-install:
+	@type $(PA11Y) >/dev/null 2>&1 || { \
+			echo "Installing \"pa11y\" from npm... \n"; \
+			mkdir -p $(SPHINXDIR)/node_modules/ ; \
+			npm install --prefix $(SPHINXDIR) pa11y; \
+		}
+
+install: $(VENVDIR)
+
+run: install
+	. $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
+html: install
+	. $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+
+epub: install
+	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+
+serve: html
+	cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000
+
+clean: clean-doc
+	@test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
+	rm -rf $(VENVDIR)
+	rm -rf $(SPHINXDIR)/node_modules/
+	rm -rf $(SPHINXDIR)/styles
+	rm -rf $(SPHINXDIR)/vale.ini
+
+clean-doc:
+	git clean -fx "$(BUILDDIR)"
+	rm -rf $(SPHINXDIR)/.doctrees
+
+spellcheck: spellcheck-install
+	. $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
+
+spelling: html spellcheck
+
+linkcheck: install
+	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
+	exit 0
+
+woke: woke-install
+	woke $(ALLFILES) --exit-1-on-failure \
+-c https://raw.githubusercontent.com/canonical/Inclusive-naming/main/config.yml
+
+pa11y: pa11y-install html
+	find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
+
+vale: install
+	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
+	@. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py
+	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \;
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+	@cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+	@echo ""
+	@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
+	@echo ""
+	@. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET) || true
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+
+pdf-prep: install
+	@for packageName in $(REQPDFPACKS); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \
+        grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \
+        (echo "\nPDF generation requires the installation of the following packages: $(REQPDFPACKS)" && \
+        echo "" && echo "Run 'sudo make pdf-prep-force' to install these packages" && echo "" && echo \
+        "Please be aware these packages will be installed to your system") && exit 1 ; done
+
+pdf-prep-force:
+	apt-get update
+	apt-get upgrade -y
+	apt-get install --no-install-recommends -y $(REQPDFPACKS) \
+
+pdf: pdf-prep
+	@. $(VENV); sphinx-build -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	@rm ./$(BUILDDIR)/latex/front-page-light.pdf || true
+	@rm ./$(BUILDDIR)/latex/normal-page-footer.pdf || true
+	@find ./$(BUILDDIR)/latex -name "*.pdf" -exec mv -t ./$(BUILDDIR) {} +
+	@rm -r $(BUILDDIR)/latex
+	@echo "\nOutput can be found in ./$(BUILDDIR)\n"
+
+allmetrics: html
+	@echo "Recording documentation metrics..."
+	@echo "Checking for existence of vale..."
+	. $(VENV)
+	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
+	@. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py
+	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \;
+	@eval '$(METRICSDIR)/source_metrics.sh $(PWD)'
+	@eval '$(METRICSDIR)/build_metrics.sh $(PWD) $(METRICSDIR)'
+
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %:
-	$(MAKE) -f Makefile.sp sp-$@
+	. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)