Documentation improvements

.github/workflows/rst-lint.yaml

@@ -0,0 +1,30 @@
+name: Check ReST input files
+on:
+  push:
+    branches:
+      - develop
+      - master
+  pull_request:
+jobs:
+  doc8:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - name: Install dependencies
+        run: |
+          pip install setuptools packaging git-props suds
+      - name: Run conf.py
+        run: |
+          python setup.py build
+          python doc/src/conf.py
+      - name: doc8-check
+        uses: deep-entertainment/doc8-action@v4
+        with:
+          scanPaths: "doc/src"

.rtd-require

@@ -4,6 +4,5 @@ lxml
 packaging
 setuptools
 suds
-jinja2<3.1
-sphinx>=2,<3
-sphinx-rtd-theme>=0.5,<1
+sphinx-copybutton
+sphinx_rtd_theme

CHANGES.rst

@@ -2,6 +2,8 @@ Changelog
 =========
 
 
+.. _changes-1_3_0:
+
 1.3.0 (not yet released)
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -36,6 +38,8 @@ Bug fixes and minor changes
 .. _#147: https://github.com/icatproject/python-icat/pull/147
 
 
+.. _changes-1_2_0:
+
 1.2.0 (2023-10-31)
 ~~~~~~~~~~~~~~~~~~
 
@@ -84,6 +88,8 @@ Bug fixes and minor changes
 .. _#140: https://github.com/icatproject/python-icat/pull/140
 
 
+.. _changes-1_1_0:
+
 1.1.0 (2023-06-30)
 ~~~~~~~~~~~~~~~~~~
 
@@ -139,6 +145,8 @@ Bug fixes and minor changes
 .. _#129: https://github.com/icatproject/python-icat/pull/129
 
 
+.. _changes-1_0_0:
+
 1.0.0 (2022-12-21)
 ~~~~~~~~~~~~~~~~~~
 
@@ -231,6 +239,8 @@ Bug fixes and minor changes
 .. _#106: https://github.com/icatproject/python-icat/pull/106
 
 
+.. _changes-0_21_0:
+
 0.21.0 (2022-01-28)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -249,6 +259,8 @@ New features
 .. _#100: https://github.com/icatproject/python-icat/pull/100
 
 
+.. _changes-0_20_1:
+
 0.20.1 (2021-11-04)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -260,6 +272,8 @@ Bug fixes and minor changes
 .. _#96: https://github.com/icatproject/python-icat/pull/96
 
 
+.. _changes-0_20_0:
+
 0.20.0 (2021-10-29)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -296,6 +310,8 @@ Bug fixes and minor changes
 .. _#95: https://github.com/icatproject/python-icat/pull/95
 
 
+.. _changes-0_19_0:
+
 0.19.0 (2021-07-20)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -324,6 +340,8 @@ Bug fixes and minor changes
 .. _#85: https://github.com/icatproject/python-icat/pull/85
 
 
+.. _changes-0_18_1:
+
 0.18.1 (2021-04-13)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -341,6 +359,8 @@ Bug fixes and minor changes
 .. _#82: https://github.com/icatproject/python-icat/pull/82
 
 
+.. _changes-0_18_0:
+
 0.18.0 (2021-03-29)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -377,6 +397,8 @@ Bug fixes and minor changes
 .. _#80: https://github.com/icatproject/python-icat/pull/80
 
 
+.. _changes-0_17_0:
+
 0.17.0 (2020-04-30)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -468,6 +490,8 @@ Misc
 .. _#72: https://github.com/icatproject/python-icat/issues/72
 
 
+.. _changes-0_16_0:
+
 0.16.0 (2019-09-26)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -492,6 +516,8 @@ Bug fixes and minor changes
 .. _#60: https://github.com/icatproject/python-icat/pull/60
 
 
+.. _changes-0_15_1:
+
 0.15.1 (2019-07-12)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -513,6 +539,8 @@ Bug fixes and minor changes
 .. _#57: https://github.com/icatproject/python-icat/issues/57
 
 
+.. _changes-0_15_0:
+
 0.15.0 (2019-03-27)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -551,6 +579,8 @@ Bug fixes and minor changes
 .. _#54: https://github.com/icatproject/python-icat/issues/54
 
 
+.. _changes-0_14_2:
+
 0.14.2 (2018-10-25)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -563,6 +593,8 @@ Bug fixes and minor changes
   probably not need it.
 
 
+.. _changes-0_14_1:
+
 0.14.1 (2018-06-05)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -573,6 +605,8 @@ Bug fixes and minor changes
   for the Write API call.
 
 
+.. _changes-0_14_0:
+
 0.14.0 (2018-06-01)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -628,6 +662,8 @@ Bug fixes and minor changes
 .. _#48: https://github.com/icatproject/python-icat/issues/48
 
 
+.. _changes-0_13_1:
+
 0.13.1 (2017-07-12)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -640,6 +676,8 @@ Bug fixes and minor changes
 .. _#38: https://github.com/icatproject/python-icat/issues/38
 
 
+.. _changes-0_13_0:
+
 0.13.0 (2017-06-09)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -798,6 +836,8 @@ Bug fixes and minor changes
 .. _pytest-dependency: https://pypi.python.org/pypi/pytest_dependency/
 
 
+.. _changes-0_12_0:
+
 0.12.0 (2016-10-10)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -837,6 +877,8 @@ Bug fixes and minor changes
 .. _#28: https://github.com/icatproject/python-icat/issues/28
 
 
+.. _changes-0_11_0:
+
 0.11.0 (2016-06-01)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -896,6 +938,8 @@ Misc
 .. _distutils_pytest: https://github.com/RKrahl/distutils-pytest
 
 
+.. _changes-0_10_0:
+
 0.10.0 (2015-12-06)
 ~~~~~~~~~~~~~~~~~~~
 
@@ -964,6 +1008,8 @@ Bug fixes and minor changes
 .. _#15: https://github.com/icatproject/python-icat/issues/15
 
 
+.. _changes-0_9_0:
+
 0.9.0 (2015-08-13)
 ~~~~~~~~~~~~~~~~~~
 
@@ -1067,6 +1113,8 @@ Bug fixes and minor changes
 .. _#10: https://github.com/icatproject/python-icat/issues/10
 
 
+.. _changes-0_8_0:
+
 0.8.0 (2015-05-08)
 ~~~~~~~~~~~~~~~~~~
 
@@ -1156,6 +1204,8 @@ Bug fixes and minor changes
   :meth:`icat.query.Query.__repr__`.
 
 
+.. _changes-0_7_0:
+
 0.7.0 (2015-02-11)
 ~~~~~~~~~~~~~~~~~~
 
@@ -1187,6 +1237,8 @@ New features
   :meth:`icat.ids.IDSClient.getLink` method.
 
 
+.. _changes-0_6_0:
+
 0.6.0 (2014-12-15)
 ~~~~~~~~~~~~~~~~~~
 
@@ -1314,6 +1366,8 @@ Minor changes and fixes
 + Add comparison operators to class :class:`icat.listproxy.ListProxy`.
 
 
+.. _changes-0_5_1:
+
 0.5.1 (2014-07-07)
 ~~~~~~~~~~~~~~~~~~
 
@@ -1357,6 +1411,8 @@ Minor changes and fixes
   modifications, such as running 2to3 on them.
 
 
+.. _changes-0_5_0:
+
 0.5.0 (2014-06-24)
 ~~~~~~~~~~~~~~~~~~
 
@@ -1399,6 +1455,8 @@ Minor changes and fixes
 .. __: https://github.com/icatproject/icat.server/issues/112
 
 
+.. _changes-0_4_0:
+
 0.4.0 (2014-02-11)
 ~~~~~~~~~~~~~~~~~~
 
@@ -1446,6 +1504,8 @@ Minor changes and fixes
   :ref:`icatrestore <icatingest>`.
 
 
+.. _changes-0_3_0:
+
 0.3.0 (2014-01-10)
 ~~~~~~~~~~~~~~~~~~
 
@@ -1492,6 +1552,8 @@ Minor changes and fixes
 + Add example scripts :ref:`icatdump` and :ref:`icatrestore <icatingest>`.
 
 
+.. _changes-0_2_0:
+
 0.2.0 (2013-11-18)
 ~~~~~~~~~~~~~~~~~~
 
@@ -1532,6 +1594,8 @@ Minor changes and fixes
   import :mod:`icat` and :mod:`icat.config`.
 
 
+.. _changes-0_1_0:
+
 0.1.0 (2013-11-01)
 ~~~~~~~~~~~~~~~~~~
 

MANIFEST.in

@@ -10,6 +10,7 @@ include doc/examples/icatdump-*.xml
 include doc/examples/icatdump-*.yaml
 include doc/examples/ingest-*.xml
 include doc/examples/metadata-*.xml
+include doc/examples/metadata.xml
 include doc/icatdata*.xsd
 include doc/man/*
 include doc/tutorial/*.py

README.rst

@@ -21,10 +21,10 @@ is based on Suds and extends it with ICAT specific features.
 Download
 --------
 
-The latest release version can be found in the
-`Python Package Index (PyPI)`__.
+The latest release version can be found at the
+`release page on GitHub`__.
 
-.. __: `PyPI site`_
+.. __: `GitHub release`_
 
 
 Documentation
@@ -64,6 +64,6 @@ permissions and limitations under the License.
 
 
 .. _ICAT: https://icatproject.org/
-.. _PyPI site: https://pypi.org/project/python-icat/
+.. _GitHub release: https://github.com/icatproject/python-icat/releases/latest
 .. _Read the Docs site: https://python-icat.readthedocs.io/
 .. _Apache License: https://www.apache.org/licenses/LICENSE-2.0

doc/.gitignore

@@ -1,3 +1,4 @@
+/src/_meta.rst
 /devhelp/
 /dirhtml/
 /doctest/

doc/Makefile

@@ -20,6 +20,7 @@ $(BUILDERS): $(STATIC_SOURCEDIRS)
 
 distclean:
 	rm -rf doctrees $(BUILDERS)
+	rm -f src/_meta.rst
 
 $(STATIC_SOURCEDIRS):
 	mkdir $@