Merge pull request plone#1160 from plone/volto_docs

Volto docs integration

Author: stevepiercy

.gitignore

@@ -2,9 +2,10 @@
 /bin
 /include
 /lib
-/node_modules
 
 # Generated files
-package-lock.json
 pyvenv.cfg
 /_build
+
+# symlinked from submodule
+docs/volto

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "submodules/volto"]
+	path = submodules/volto
+	url = https://github.com/plone/volto.git
+	branch = plone6-docs

Makefile

@@ -1,14 +1,16 @@
 # Makefile for Sphinx documentation
-#
+.DEFAULT_GOAL   = help
+SHELL           = bash
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-DOCS_DIR      = ./docs/
-BUILDDIR      = ../_build/
+SPHINXOPTS      ?=
+PAPER           ?=
 
 # Internal variables.
+SPHINXBUILD     = $(realpath bin/sphinx-build)
+SPHINXAUTOBUILD = $(realpath bin/sphinx-autobuild)
+DOCS_DIR        = ./docs/
+BUILDDIR        = ../_build/
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
@@ -19,65 +21,74 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # Add the following 'help' target to your Makefile
 # And add help text after each target name starting with '\#\#'
 .PHONY: help
-help: ## This help message
+help:  # This help message
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
 .PHONY: clean
-clean: ## Clean build directory
-	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/*
+clean:  ## Clean docs build directory
+	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
 
-.PHONY: build
-build:  ## Set up training: Install requirements
+.PHONY: distclean
+distclean:  ## Clean docs build directory and Python virtual environment
+	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
+	rm -rf ./bin/ ./lib/ ./lib64 ./include ./pyvenv.cfg
+
+bin/python:
 	python3 -m venv . || virtualenv --clear --python=python3 .
 	bin/python -m pip install --upgrade pip
 	bin/pip install -r requirements.txt
-	@echo
-	@echo "Please activate your Python virtual environment with"
-	@echo "source bin/activate"
+
+docs/volto:
+	git submodule init; \
+	git submodule update; \
+	ln -s ../submodules/volto/docs/source ./docs/volto
+
+.PHONY: deps
+deps: bin/python docs/volto  ## Create Python virtual environment, install requirements, pull in Volto submodule
 
 .PHONY: html
-html: ## Build html
+html: deps  ## Build html
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: manual
-manual:
-	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html -t manual . manual
+manual: deps
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html -t manual . $(BUILDDIR)/manual
 
 .PHONY: dirhtml
-dirhtml:
+dirhtml: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
-singlehtml:
+singlehtml: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 .PHONY: pickle
-pickle:
+pickle: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 .PHONY: json
-json:
+json: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 .PHONY: htmlhelp
-htmlhelp:
+htmlhelp: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
 .PHONY: qthelp
-qthelp:
+qthelp: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -87,7 +98,7 @@ qthelp:
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MasteringPlone.qhc"
 
 .PHONY: devhelp
-devhelp:
+devhelp: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -97,101 +108,109 @@ devhelp:
 	@echo "# devhelp"
 
 .PHONY: epub
-epub:
+epub: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 .PHONY: latex
-latex:
+latex: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 .PHONY: latexpdf
-latexpdf:
+latexpdf: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 .PHONY: text
-text:
+text: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
 .PHONY: man
-man:
+man: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
 .PHONY: texinfo
-texinfo:
+texinfo: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
 .PHONY: info
-info:
+info: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
 
 .PHONY: changes
-changes:
+changes: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 .PHONY: linkcheck
-linkcheck: ## Run linkcheck
+linkcheck: deps  ## Run linkcheck
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 		"or in $(BUILDDIR)/linkcheck/ ."
 
 .PHONY: linkcheckbroken
-linkcheckbroken: ## Run linkcheck and show only broken links
+linkcheckbroken: deps  ## Run linkcheck and show only broken links
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | GREP_COLORS='0;31' egrep -wi broken --color=auto
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 		"or in $(BUILDDIR)/linkcheck/ ."
 
 .PHONY: spellcheck
-spellcheck: ## Run spellcheck
+spellcheck: deps  ## Run spellcheck
 	cd $(DOCS_DIR) && LANGUAGE=$* $(SPHINXBUILD) -b spelling -j 4 $(ALLSPHINXOPTS) $(BUILDDIR)/spellcheck/$*
 	@echo
 	@echo "Spellcheck is finished; look for any errors in the above output " \
 		" or in $(BUILDDIR)/spellcheck/ ."
 
 .PHONY: html_meta
-html_meta:
+html_meta: deps  ## Add meta data headers to all Markdown pages
 	python ./docs/addMetaData.py
 
 .PHONY: doctest
-doctest:
+doctest: deps
 	cd $(DOCS_DIR) && $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
 .PHONY: test
-test: clean linkcheck spellcheck  ## Run linkcheck, spellcheck
+test: clean linkcheck spellcheck  ## Clean docs build, then run linkcheck, spellcheck
 
 .PHONY: deploy
 deploy: clean html
 
 .PHONY: livehtml
-livehtml:  ## Rebuild Sphinx documentation on changes, with live-reload in the browser
-	cd "$(DOCS_DIR)" && sphinx-autobuild \
+livehtml: deps  ## Rebuild Sphinx documentation on changes, with live-reload in the browser
+	cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \
 		--ignore "*.swp" \
 		-b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
 
+.PHONY: netlify
+netlify:
+	pip install -r requirements.txt
+	git submodule init; \
+	git submodule update; \
+	ln -s ../submodules/volto/docs/source ./docs/volto
+	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
 .PHONY: all
-all: clean spellcheck linkcheck html ## Run checks and build html
+all: clean spellcheck linkcheck html  ## Clean docs build, then run linkcheck and spellcheck, and build html

docs/_static/edit-pencil-icon.png

@@ -69,6 +69,7 @@
 linkcheck_ignore = [
     # TODO: Before release, clean up any links to ignore
     r"http://localhost",
+    r"http://0.0.0.0",
     r"http://127.0.0.1",
     r"https://www.linode.com/",
     r"https://github.com/plone/documentation/issues/new/choose",  # requires auth

docs/conf.py

@@ -0,0 +1,36 @@
+---
+html_meta:
+  "description": "Administrators' guide to writing Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation."
+  "property=og:description": "Administrators' guide to writing Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation."
+  "property=og:title": "Administrators Guide"
+  "keywords": "Plone, Documentation, automated deployments, hosting, automated testing, importing external packages"
+---
+
+(administrators-guide-label)=
+
+# Administrators Guide
+
+This guide is for administrators of Plone Documentation.
+It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation.
+
+
+(administrators-import-docs-submodule-label)=
+
+## Importing external docs with submodules
+
+To add an external package to Plone Documentation, we use git submodules.
+We did this with Volto documentation.
+Your package must be available under the Plone GitHub organization.
+
+Inside the repository `plone/documentation`, add a git submodule that points to your project.
+
+```shell
+git submodule add [email protected]:plone/my_package.git submodules/my_package
+```
+
+To make it easier for other contributors to work with your project, update the following files, using `volto` as a model.
+ 
+-   `Makefile` targets  `docs/my_package` and `deps`
+-   The documentation section {ref}`contributing-editing-volto-documentation-label`
+
+Commit and push your changes to a remote, and submit a pull request against [`plone/documentation@6-dev`](https://github.com/plone/documentation/compare).