add releasenote and docs config

This change stubs out the docs and release note
structure and set up the inintal jobs to build
and publish docs and releasenotes.

This invovle adding a bindep.txt to capture
the binary packages requried for html and pdf docs,
extending tox with the standard docs targets,
provideing a doc/requirement.txt to track the
doc only python deps and a standard folder structure.

Change-Id: Iffbef50ab806688a6d62f27ab60fa824edcb3d09

.zuul.yaml

@@ -1,4 +1,9 @@
 - project:
+    # Please try to keep the list of job names sorted alphabetically.
+    templates:
+      - check-requirements
+      - publish-openstack-docs-pti
+      - release-notes-jobs-python3
     check:
       jobs:
         - openstack-tox-pep8:

bindep.txt

@@ -0,0 +1,21 @@
+# This is a cross-platform list tracking distribution packages needed for install and tests;
+# see https://docs.openstack.org/infra/bindep/ for additional information.
+build-essential [platform:dpkg test]
+gcc [platform:rpm test]
+language-pack-en [platform:ubuntu]
+locales [platform:debian]
+python3-all [platform:dpkg test]
+python3-all-dev [platform:dpkg test]
+python3 [platform:rpm test]
+python3-devel [platform:rpm test]
+libpcre3-dev [platform:dpkg test]
+pcre-devel [platform:rpm test]
+# gettext and graphviz are needed by doc builds only.
+gettext [doc]
+graphviz [doc]
+# fonts-freefont-otf is needed for pdf docs builds with the 'xelatex' engine
+fonts-freefont-otf [pdf-docs]
+texlive [pdf-docs]
+texlive-latex-recommended [pdf-docs]
+texlive-xetex [pdf-docs]
+latexmk [pdf-docs]

doc/Makefile

@@ -0,0 +1,20 @@
+# 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".
+help:
+    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)

doc/requirements.txt

@@ -0,0 +1,7 @@
+openstackdocstheme>=2.2.0 # Apache-2.0
+
+# releasenotes
+reno>=3.1.0 # Apache-2.0
+sphinx>=2.1.1 # BSD
+sphinx-feature-classification>=1.1.0 # Apache-2.0
+sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD

doc/source/conf.py

@@ -0,0 +1,99 @@
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+# project info
+project = "grian-ui"
+author = "OpenStack <openstack-discuss@lists.openstack.org>"
+
+# The master toctree document.
+master_doc = "index"
+
+# General information about the project.
+copyright = "2010-present, OpenStack Foundation"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "openstackdocstheme",
+]
+
+exclude_patterns = []
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "native"
+
+# A list of ignored prefixes for module index sorting.
+modindex_common_prefix = ["grian_ui."]
+
+# -- Options for Internationalization output ------------------------------
+locale_dirs = ["locale/"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "openstackdocs"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# If false, no index is generated.
+html_use_index = False
+
+# -- Options for LaTeX output ---------------------------------------------
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (
+        "index",
+        "doc-grian-ui.tex",
+        "Grian-UI Release Notes Documentation",
+        "OpenStack <openstack-discuss@lists.openstack.org>",
+        "manual",
+    ),
+]
+
+latex_domain_indices = False
+
+latex_elements = {
+    "makeindex": "",
+    "printindex": "",
+    "preamble": r"\setcounter{tocdepth}{3}",
+    "maxlistdepth": "10",
+}
+
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+latex_use_xindy = False
+
+# Disable smartquotes, they don't work in latex
+smartquotes_excludes = {"builders": ["latex"]}
+
+# -- Options for openstackdocstheme ---------------------------------------
+
+openstackdocs_repo_name = "openstack/grian-ui"
+openstackdocs_bug_project = "grian-ui"
+openstackdocs_bug_tag = ""
+openstackdocs_pdf_link = True
+
+# The suffix of source filenames.
+source_suffix = ".rst"

doc/source/index.rst

@@ -0,0 +1,16 @@
+.. Grian-UI documentation master file, created by
+   sphinx-quickstart on Mon May 19 12:01:22 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Grian-UI documentation
+======================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:

releasenotes/Makefile

@@ -0,0 +1,20 @@
+# 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".
+help:
+    @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)

releasenotes/source/conf.py

@@ -0,0 +1,63 @@
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "grian-ui"
+copyright = "2025, OpenStack <openstack-discuss@lists.openstack.org>"
+author = "OpenStack <openstack-discuss@lists.openstack.org>"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "openstackdocstheme",
+    "reno.sphinxext",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+# -- Options for Internationalization output ------------------------------
+locale_dirs = ["locale/"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "openstackdocs"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# If false, no index is generated.
+html_use_index = False
+
+# -- Options for LaTeX output ---------------------------------------------
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (
+        "index",
+        "GrianUIReleaseNotes.tex",
+        "Grian-UI Release Notes Documentation",
+        "OpenStack <openstack-discuss@lists.openstack.org>",
+        "manual",
+    ),
+]
+
+# -- Options for openstackdocstheme ---------------------------------------
+
+openstackdocs_repo_name = "openstack/grian-ui"
+openstackdocs_bug_project = "grian-ui"
+openstackdocs_bug_tag = ""

releasenotes/source/index.rst

@@ -0,0 +1,8 @@
+======================
+Grian-UI Release Notes
+======================
+
+.. toctree::
+   :maxdepth: 1
+
+   unreleased

releasenotes/source/unreleased.rst

@@ -0,0 +1,5 @@
+==============================
+ Current Series Release Notes
+==============================
+
+.. release-notes::

test-requirements.txt

@@ -1,6 +1,6 @@
 coverage>=4.4.1 # Apache-2.0
 ddt>=1.2.1 # MIT
-django
+Django>=4.2 # BSD
 fixtures>=3.0.0 # Apache-2.0/BSD
 hacking==6.1.0 # Apache-2.0
 oslotest>=3.8.0 # Apache-2.0

tox.ini

@@ -70,6 +70,29 @@ deps =
 commands =
     {posargs}
 
+[testenv:releasenotes]
+deps =
+    {[testenv]deps}
+    -r{toxinidir}/doc/requirements.txt
+commands = sphinx-build -a -W -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+
+[testenv:docs]
+description =
+  Build all documentation including API guides and refs.
+deps = -r{toxinidir}/doc/requirements.txt
+commands =
+  rm -rf doc/build
+  sphinx-build -W --keep-going -b html -j auto doc/source doc/build/html
+
+[testenv:pdf-docs]
+description =
+  Build PDF documentation.
+deps = {[testenv:docs]deps}
+extras =
+commands =
+  rm -rf doc/build/pdf
+  sphinx-build -W --keep-going -b latex -j auto doc/source doc/build/pdf
+  make -C doc/build/pdf
 
 [flake8]
 # We only enable the hacking (H) and local checks (N)