Minor doc improvements

Details:

* Simplified the Installation section by merging a subchapter into the
  Installation chapter.

* Corrected the set of tested OS environments to no longer contain CygWin.

* Removed the prerequisites packages setuptools, pip and wheel for installation,
  since pip does not have any requirements on setuptools or wheel.

* Removed the "Python namespace" section and moved the statement about
  describing only the external API to the begin of the "API Reference"
  section.

* Specified language 'en' for the docs building in conf.py, to eliminate
  a corresponding warning during docs building.

* Generalized the version 3.4 to 3 in the link to the Python 3 glossary.

* Added 'make doclinkcheck' to the GitHub Actions test workflow, and
  documented this make target in 'make help' and added it to 'make all'.

Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>

.github/workflows/test.yml

@@ -235,6 +235,11 @@ jobs:
         # TESTCASES: test_cim_obj.py
       run: |
         make test
+    - name: Run doclinkcheck
+      env:
+        PACKAGE_LEVEL: ${{ matrix.package_level }}
+      run: |
+        make doclinkcheck
     - name: Send coverage result to coveralls.io
       shell: bash -l {0}
       env:

Makefile

@@ -261,6 +261,7 @@ help:
 	@echo "  installtest - Run install tests"
 	@echo "  test       - Run unit tests"
 	@echo "  testdict   - Run unit tests against standard dict"
+	@echo "  doclinkcheck - Run Sphinx linkcheck on the documentation"
 	@echo "  all        - Do all of the above"
 	@echo "  install    - Install $(package_name) as standalone and its dependent packages"
 	@echo "  upload     - build + upload the distribution archive files to PyPI"
@@ -427,7 +428,7 @@ pylint: pylint_$(pymn).done
 	@echo "Makefile: Target $@ done."
 
 .PHONY: all
-all: develop build builddoc check pylint installtest test testdict
+all: develop build builddoc check pylint installtest test testdict doclinkcheck
 	@echo "Makefile: Target $@ done."
 
 .PHONY: clobber

docs/appendix.rst

@@ -17,7 +17,7 @@ References
 
    Python Glossary
       * `Python 2.7 Glossary <https://docs.python.org/2.7/glossary.html>`_
-      * `Python 3.4 Glossary <https://docs.python.org/3.4/glossary.html>`_
+      * `Python 3 Glossary <https://docs.python.org/3/glossary.html>`_
 
    Default Case Folding in The Unicode Standard
-     `"Default Case Folding" in The Unicode Standard Version 15.0 <https://www.unicode.org/versions/Unicode15.0.0/ch03.pdf#G53253>`_
+     `"Default Case Folding" in The Unicode Standard Version 15.0 <https://www.unicode.org/versions/Unicode15.0.0/ch03.pdf>`_

docs/conf.py

@@ -120,7 +120,7 @@ def get_version(version_file):
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # By default, highlight as Python 3.
 highlight_language = 'python3'

docs/intro.rst

@@ -114,11 +114,11 @@ Supported environments
 ^^^^^^^^^^^^^^^^^^^^^^
 
 The package does not have any dependencies on the type of operating system and
-is regularly tested in CI systems on the following operating systems:
+is regularly tested in GitHub Actions on the following operating systems:
 
-* Ubuntu, native Windows, CygWin, OS-X / macOS
+* Ubuntu, Windows, macOS
 
-The package is supported on the following Python versions:
+The package is supported and tested on the following Python versions:
 
 * Python: 2.7, 3.4 and all higher 3.x versions
 
@@ -128,55 +128,31 @@ The package is supported on the following Python versions:
 Installing
 ^^^^^^^^^^
 
-* Prerequisites:
+The following command installs the latest version of nocasedict that is
+released on `PyPI`_ into the active Python environment:
 
-  - The Python environment into which you want to install must be the current
-    Python environment, and must have at least the following Python packages
-    installed:
-
-    - setuptools
-    - wheel
-    - pip
-
-* Install the nocasedict package and its prerequisite
-  Python packages into the active Python environment:
-
-  .. code-block:: bash
-
-      $ pip install nocasedict
-
-
-.. _`Installing a different version`:
-
-Installing a different version
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: bash
 
-The examples in the previous sections install the latest version of
-nocasedict that is released on `PyPI`_.
-This section describes how different versions of nocasedict
-can be installed.
+    $ pip install nocasedict
 
-* To install an older released version of nocasedict,
-  Pip supports specifying a version requirement. The following example installs
-  nocasedict version 0.1.0
-  from PyPI:
+To install an older released version of nocasedict, Pip supports specifying a
+version requirement. The following example installs nocasedict version 0.1.0
+from PyPI into the active Python environment:
 
-  .. code-block:: bash
+.. code-block:: bash
 
-      $ pip install nocasedict==0.1.0
+    $ pip install nocasedict==0.1.0
 
-* If you need to get a certain new functionality or a new fix that is
-  not yet part of a version released to PyPI, Pip supports installation from a
-  Git repository. The following example installs nocasedict
-  from the current code level in the master branch of the
-  `nocasedict repository`_:
+If you need to get a certain new functionality or a new fix that is not yet part
+of a version released to PyPI, Pip supports installation from a Git repository.
+The following example installs nocasedict from the current code level in the
+master branch of the `nocasedict repository`_:
 
-  .. code-block:: bash
+.. code-block:: bash
 
-      $ pip install git+https://github.com/pywbem/nocasedict.git@master#egg=nocasedict
+    $ pip install git+https://github.com/pywbem/nocasedict.git@master#egg=nocasedict
 
 .. _nocasedict repository: https://github.com/pywbem/nocasedict
-
 .. _PyPI: https://pypi.python.org/pypi
 
 
@@ -277,13 +253,3 @@ the nocasedict project, by version type:
 * New major release (M.N.P -> M+1.0.0): Deprecated functionality may get
   removed; functionality may be extended or changed; backwards compatibility
   may be broken.
-
-
-.. _'Python namespaces`:
-
-Python namespaces
------------------
-
-This documentation describes only the external APIs of the
-nocasedict project, and omits any internal symbols and
-any sub-modules.

docs/reference.rst

@@ -4,6 +4,9 @@
 API Reference
 =============
 
+This section describes the external API of the nocasedict project. Any
+internal symbols and APIs are omitted.
+
 
 .. _`Class NocaseDict`: