From 278da4103ecbfa19eaab78c4712e36e029eaa7d9 Mon Sep 17 00:00:00 2001 From: Scott Davidson Date: Mon, 31 Oct 2022 20:16:04 +0000 Subject: [PATCH 1/6] Add basic docs template structure --- tox.ini | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/tox.ini b/tox.ini index 787fe1044..ef2a6989c 100644 --- a/tox.ini +++ b/tox.ini @@ -23,3 +23,13 @@ deps = commands = rm -rf releasenotes/build/html sphinx-build -n -W --keep-going -b html releasenotes/source releasenotes/build/html + +[testenv:docs] +deps = + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/doc/requirements.txt +commands = + rm -rf doc/build/html + sphinx-build -b html doc/source doc/build/html + ; sphinx-build -W --keep-going -b html doc/source doc/build/html + ; whereto doc/source/_extra/.htaccess doc/test/redirect-tests.txt \ No newline at end of file From 05df5fa8fa41cb39a7fac70cde2c13225d701c32 Mon Sep 17 00:00:00 2001 From: Scott Davidson Date: Mon, 31 Oct 2022 20:16:04 +0000 Subject: [PATCH 2/6] Add basic docs template structure --- doc/requirements.txt | 9 ++++ doc/source/conf.py | 98 ++++++++++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 27 ++++++++++++ 3 files changed, 134 insertions(+) create mode 100644 doc/requirements.txt create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 000000000..51a2c6498 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,9 @@ +# The order of packages is significant, because pip processes them in the order +# of appearance. Changing the order has an impact on the overall integration +# process, which may cause wedges in the gate later. + +openstackdocstheme>=2.2.1 # Apache-2.0 +reno>=3.1.0 # Apache-2.0 +sphinx>=2.0.0,!=2.1.0 # BSD +sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD +whereto>=0.3.0 # Apache-2.0 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 000000000..39fbb51ac --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,98 @@ +# Copyright (c) 2017 StackHPC Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +# -*- coding: utf-8 -*- +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import openstackdocstheme + + +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + # 'openstackdocstheme', + #'sphinx.ext.autodoc', + #'sphinx.ext.intersphinx', + 'sphinxcontrib.rsvgconverter', +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'kayobe-config' +# copyright = '2013, OpenStack Foundation' + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'native' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = [] +html_theme = 'default' +# html_static_path = ['static'] + +# Add any paths that contain "extra" files, such as .htaccess or +# robots.txt. +html_extra_path = ['_extra'] + +html_theme_options = { + "show_other_versions": True, +} + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +# latex_documents = [ +# ('index', +# 'doc-%s.tex' % project, +# '%s Documentation' % project, +# 'OpenStack Foundation', 'manual'), +# ] + +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +latex_use_xindy = False + diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 000000000..b04bb46ad --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,27 @@ +.. kayobe documentation master file, created by + sphinx-quickstart on Tue Jul 9 22:26:36 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +================================================== +Welcome to StackHPC's Kayobe Config documentation! +================================================== + + +Overview +======== + + + +Contents +======== + + + +Intro +===== + + + +Contributors Guide +================= From debe0d6a38c7325eb9ba3d61e8e6d6341a5e4de8 Mon Sep 17 00:00:00 2001 From: Scott Davidson Date: Mon, 31 Oct 2022 20:22:57 +0000 Subject: [PATCH 3/6] Add basic docs template structure --- doc/requirements.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 51a2c6498..95b160c9c 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,8 +2,6 @@ # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. -openstackdocstheme>=2.2.1 # Apache-2.0 reno>=3.1.0 # Apache-2.0 sphinx>=2.0.0,!=2.1.0 # BSD sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD -whereto>=0.3.0 # Apache-2.0 From 020e29f2075ca4add2eb05fca154bf643ec88efb Mon Sep 17 00:00:00 2001 From: Scott Davidson Date: Mon, 31 Oct 2022 20:22:57 +0000 Subject: [PATCH 4/6] Add basic docs template structure --- doc/source/conf.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 39fbb51ac..e15654d3a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -26,15 +26,11 @@ # See the License for the specific language governing permissions and # limitations under the License. -import openstackdocstheme - - # -- General configuration ---------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ - # 'openstackdocstheme', #'sphinx.ext.autodoc', #'sphinx.ext.intersphinx', 'sphinxcontrib.rsvgconverter', From 0ae82c333a583ecf9fa68b455b4ca2c124ba201e Mon Sep 17 00:00:00 2001 From: Scott Davidson Date: Mon, 31 Oct 2022 20:53:27 +0000 Subject: [PATCH 5/6] Remove openstack reference --- doc/source/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index e15654d3a..b3f378449 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -48,7 +48,6 @@ # General information about the project. project = 'kayobe-config' -# copyright = '2013, OpenStack Foundation' # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True From 32d3c7988807aa47d75b8a81e84ceef6ba9b33c8 Mon Sep 17 00:00:00 2001 From: Scott Davidson Date: Tue, 1 Nov 2022 13:22:17 +0000 Subject: [PATCH 6/6] Changes based on Mark's comments --- .github/workflows/stackhpc-pull-request.yml | 2 ++ doc/source/conf.py | 6 +++--- doc/source/index.rst | 2 +- tox.ini | 8 ++++---- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/.github/workflows/stackhpc-pull-request.yml b/.github/workflows/stackhpc-pull-request.yml index da4760a84..0504103d3 100644 --- a/.github/workflows/stackhpc-pull-request.yml +++ b/.github/workflows/stackhpc-pull-request.yml @@ -14,6 +14,8 @@ jobs: python-version: 3.8 - environment: releasenotes python-version: 3.8 + - environment: docs + python-version: 3.8 name: Tox ${{ matrix.environment }} with Python ${{ matrix.python-version }} if: github.repository == 'stackhpc/stackhpc-kayobe-config' steps: diff --git a/doc/source/conf.py b/doc/source/conf.py index b3f378449..f7214fed0 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -47,7 +47,7 @@ master_doc = 'index' # General information about the project. -project = 'kayobe-config' +project = 'stackhpc-kayobe-config' # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True @@ -69,10 +69,10 @@ # Add any paths that contain "extra" files, such as .htaccess or # robots.txt. -html_extra_path = ['_extra'] +# html_extra_path = ['_extra'] html_theme_options = { - "show_other_versions": True, + # "show_other_versions": True, } # Output file base name for HTML help builder. diff --git a/doc/source/index.rst b/doc/source/index.rst index b04bb46ad..24f01975d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -24,4 +24,4 @@ Intro Contributors Guide -================= +================== diff --git a/tox.ini b/tox.ini index ef2a6989c..5e1f5a7cb 100644 --- a/tox.ini +++ b/tox.ini @@ -25,11 +25,11 @@ commands = sphinx-build -n -W --keep-going -b html releasenotes/source releasenotes/build/html [testenv:docs] +allowlist_externals = rm +skip_install = true deps = - -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/xena} -r{toxinidir}/doc/requirements.txt commands = rm -rf doc/build/html - sphinx-build -b html doc/source doc/build/html - ; sphinx-build -W --keep-going -b html doc/source doc/build/html - ; whereto doc/source/_extra/.htaccess doc/test/redirect-tests.txt \ No newline at end of file + sphinx-build -W --keep-going -b html doc/source doc/build/html \ No newline at end of file