Added documentation

Signed-off-by: Andreas Maier <maiera@de.ibm.com>

.github/workflows/test.yml

@@ -153,12 +153,12 @@ jobs:
         RUN_TYPE: ${{ steps.set-run-type.outputs.result }}
       run: |
         make build
-    # - name: Run builddoc
-    #   env:
-    #     PACKAGE_LEVEL: ${{ matrix.package_level }}
-    #     RUN_TYPE: ${{ steps.set-run-type.outputs.result }}
-    #   run: |
-    #     make builddoc
+    - name: Run builddoc
+      env:
+        PACKAGE_LEVEL: ${{ matrix.package_level }}
+        RUN_TYPE: ${{ steps.set-run-type.outputs.result }}
+      run: |
+        make builddoc
     - name: Run check
       env:
         PACKAGE_LEVEL: ${{ matrix.package_level }}

Makefile

@@ -151,7 +151,7 @@ doc_dir := docs
 
 # Directory for generated API documentation
 doc_build_dir := build_docs
-doc_build_file := $(doc_build_dir)/html/docs/index.html
+doc_build_file := $(doc_build_dir)/index.html
 
 # Dependents for Sphinx documentation build
 doc_dependent_files := \
@@ -164,12 +164,11 @@ doc_dependent_files := \
 check_py_files := \
     $(package_py_files) \
     $(test_py_files) \
-# TODO: Add conf.py once docs are created
-#    $(doc_dir)/conf.py \
+    $(doc_dir)/conf.py \
 
 # Documentation generator command
 doc_cmd := sphinx-build
-doc_opts := -v -d $(doc_build_dir)/doctrees -c $(doc_dir) .
+doc_opts := -v -c $(doc_dir)
 
 # Directory for .done files
 done_dir := done
@@ -363,7 +362,7 @@ $(done_dir)/install_$(pymn)_$(PACKAGE_LEVEL).done: $(done_dir)/base_$(pymn)_$(PA
 $(doc_build_file): $(done_dir)/develop_$(pymn)_$(PACKAGE_LEVEL).done Makefile $(doc_dependent_files)
 	@echo "Makefile: Creating the HTML pages with top level file: $@"
 	-$(call RM_FUNC,$@)
-	$(doc_cmd) -b html $(doc_opts) $(doc_build_dir)/html
+	$(doc_cmd) -b html $(doc_opts) $(doc_dir) $(doc_build_dir)
 	@echo "Done: Created the HTML pages with top level file: $@"
 
 $(sdist_file): $(done_dir)/develop_$(pymn)_$(PACKAGE_LEVEL).done Makefile $(dist_dependent_files)

docs/_static/my_theme.css

@@ -0,0 +1,4 @@
+
+.wy-nav-content {
+  max-width: 1000px !important;
+}

docs/appendix.rst

@@ -0,0 +1,68 @@
+.. Copyright 2024 IBM Corp. All Rights Reserved.
+..
+.. 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.
+
+Appendix
+========
+
+
+Glossary
+--------
+
+.. glossary::
+
+   IBM Z
+      IBM's mainframe product line
+
+   Z HMC
+      Hardware Management Console for IBM Z
+
+Bibliography
+------------
+
+.. glossary::
+
+   HMC API
+       The Web Services API of the z Systems Hardware Management Console, described in the following books:
+
+   HMC API 2.11.1
+       `IBM SC27-2616, System z Hardware Management Console Web Services API (Version 2.11.1) <https://www.ibm.com/support/pages/node/6017542>`_
+
+   HMC API 2.12.0
+       `IBM SC27-2617, System z Hardware Management Console Web Services API (Version 2.12.0) <https://www.ibm.com/support/pages/node/6019030>`_
+
+   HMC API 2.12.1
+       `IBM SC27-2626, System z Hardware Management Console Web Services API (Version 2.12.1) <https://www.ibm.com/support/pages/node/6017614>`_
+
+   HMC API 2.13.0
+       `IBM SC27-2627, z Systems Hardware Management Console Web Services API (Version 2.13.0) <https://www.ibm.com/support/pages/node/6018628>`_
+
+   HMC API 2.13.1
+       `IBM SC27-2634, z Systems Hardware Management Console Web Services API (Version 2.13.1) <https://www.ibm.com/support/pages/node/6019732>`_
+
+   HMC API 2.14.0
+       `IBM SC27-2636, IBM Z Hardware Management Console Web Services API (Version 2.14.0) <https://www.ibm.com/support/pages/node/6020008>`_
+
+   HMC API 2.14.1
+       `IBM SC27-2637, IBM Z Hardware Management Console Web Services API (Version 2.14.1) <https://www.ibm.com/support/pages/node/6019768>`_
+
+   HMC API 2.15.0
+       `IBM SC27-2638, IBM Z Hardware Management Console Web Services API (Version 2.15.0) <https://www.ibm.com/support/pages/node/6019720>`_
+       (covers both GA1 and GA2)
+
+   HMC Security
+       `Hardware Management Console Security <https://www.ibm.com/support/pages/node/6017320>`_
+
+   CADF
+   Cloud Auditing Data Federation
+       `DMTF Cloud Auditing Data Federation standard <https://www.dmtf.org/standards/cadf>`_

docs/changes.rst

@@ -0,0 +1,40 @@
+.. Copyright 2024 IBM Corp. All Rights Reserved.
+..
+.. 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.
+
+
+Change log
+----------
+
+.. ============================================================================
+..
+.. Do not add change records here directly, but create fragment files instead!
+..
+.. ============================================================================
+
+.. towncrier start
+
+Version 0.12.0
+^^^^^^^^^^^^^^
+
+Released: 2024-06-14
+
+Version 0.11.0
+^^^^^^^^^^^^^^
+
+Released: 2024-06-12
+
+Version 0.10.0
+^^^^^^^^^^^^^^
+
+Released: 2024-03-18

docs/conf.py

@@ -0,0 +1,183 @@
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# pylint: disable=invalid-name
+
+"""
+Config file for Sphinx.
+"""
+
+import setuptools_scm
+
+
+def setup(app):
+    """Setup for the module"""
+    app.add_css_file('my_theme.css')
+
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'IBM Z HMC Log Forwarder'
+copyright = '2019, IBM Corp'  # pylint: disable=redefined-builtin
+author = 'Andreas Maier'
+
+# The full version, including alpha/beta/rc tags
+release = setuptools_scm.get_version(root='..', relative_to=__file__)
+
+# The short M.N.U version, displayed in the docs.
+# We also use the full version for that.
+version = release
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+needs_sphinx = '1.8.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autosectionlabel',
+    'sphinx_rtd_theme',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'changes', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.
+# See http://www.sphinx-doc.org/en/stable/theming.html for built-in themes.
+html_theme = "sphinx_rtd_theme"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.
+# See http://www.sphinx-doc.org/en/stable/theming.html for the options
+# available for built-in themes.
+# For options of the 'sphinx_rtd_theme', see
+# https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html
+html_theme_options = {
+    'style_external_links': False,
+    'collapse_navigation': False,
+}
+
+# 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']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'zhmc_log_forwarder_doc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# 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 = [
+    (master_doc,
+     'zhmc_log_forwarder.tex',
+     'zhmc\\_log\\_forwarder Documentation',
+     'Andreas Maier',
+     'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc,
+     'zhmc_log_forwarder',
+     'zhmc_log_forwarder Documentation',
+     [author],
+     1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc,
+     'zhmc_log_forwarder',
+     'zhmc_log_forwarder Documentation',
+     author,
+     'zhmc_log_forwarder',
+     'One line description of project.',
+     'Miscellaneous'),
+]