docs: misc sphinx docs tidy-ups (#165)

Makefile

@@ -14,17 +14,12 @@ docs.sphinx.html:
 	# /docs/source for each public module in the pyoda_time package
 	# recursively. Those files will contain directives (e.g. :automodule:)
 	# which can later be handled by the autodoc extension.
-	# The default behaviour for sphinx-apidoc directs autodoc to include
-	# :members:, :undoc-members: and :show-inheritance:.
-	# We don't want inheritance to be shown, hence we explicitly set
-	# the SPHINX_APIDOC_OPTIONS environment variable as per the docs.
-	# https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html#envvar-SPHINX_APIDOC_OPTIONS
-	SPHINX_APIDOC_OPTIONS=members,undoc-members poetry run sphinx-apidoc -fe -d 1 -o docs/source pyoda_time pyoda_time/version.py
+	poetry run sphinx-apidoc -o docs/source pyoda_time
 
 	@echo "Building html docs with sphinx-autodoc"
 	# Uses the sphinx Makefile in /docs to build the documentation.
 	# The autodoc extension is enabled in /docs/conf.py.
 	# That extensions interprets the directives in the files which were
 	# generated by sphinx-apidoc in the previous command, allowing
 	# us to turn that into html documentation.
-	poetry run make -C docs html
+	poetry run make -C docs SPHINXOPTS=-W html

docs/source/conf.py

@@ -61,6 +61,7 @@
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options
 autodoc_class_signature = "separated"
 autodoc_default_options = {
+    "show-inheritance": True,
     "special-members": ",".join(
         [
             "__add__",
@@ -130,17 +131,29 @@ def process_metaclass_properties(
                 ]
 
                 # Add the property docstring, formatted as reStructuredText field lists.
-                for line in property_docstring.splitlines():
+                for paragraph in property_docstring.split("\n\n"):
                     # Sphinx is really finicky about whitespace, so we
                     # need to take control of that here.
-                    line = line.strip()
+                    paragraph = paragraph.strip()
 
-                    if line.startswith(":"):
+                    if paragraph.startswith(":"):
                         # It's a field list, so we make sure it's properly indented.
-                        doc_lines.append(f"   {line}")
+                        current_field = ""
+                        for line in paragraph.splitlines():
+                            line = line.strip()
+                            if line.startswith(":"):
+                                if current_field:
+                                    doc_lines.append(f"   {current_field.strip()}")
+                                current_field = line
+                            else:
+                                current_field += " " + line
+                        doc_lines.append(f"   {current_field.strip()}")
+
                     else:
                         # It's a regular line of the docstring, so we add it as is.
-                        doc_lines.append(f"      {line}")
+                        paragraph = " ".join(line.strip() for line in paragraph.splitlines())
+                        doc_lines.append(f"      {paragraph}")
+
                     doc_lines.append("")
 
                 lines.extend(doc_lines)

docs/source/index.rst

@@ -7,10 +7,10 @@ Welcome to Pyoda Time's documentation!
 ======================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 4
    :caption: Contents:
 
-   API Reference <pyoda_time>
+   modules
 
 
 

docs/source/modules.rst

@@ -2,6 +2,6 @@ pyoda_time
 ==========
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 4
 
    pyoda_time

docs/source/pyoda_time.rst

@@ -5,7 +5,7 @@ Subpackages
 -----------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 4
 
    pyoda_time.calendars
    pyoda_time.fields

docs/source/pyoda_time.testing.rst

@@ -5,7 +5,7 @@ Subpackages
 -----------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 4
 
    pyoda_time.testing.time_zones
 

docs/source/pyoda_time.text.rst

@@ -5,7 +5,7 @@ Subpackages
 -----------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 4
 
    pyoda_time.text.patterns
 

docs/source/pyoda_time.time_zones.rst

@@ -5,7 +5,7 @@ Subpackages
 -----------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 4
 
    pyoda_time.time_zones.cldr
    pyoda_time.time_zones.io

pyoda_time/_calendar_system.py

@@ -576,7 +576,7 @@ def _get_year_month_day_calendar_from_days_since_epoch(self, days_since_epoch: i
 
     # region object overrides
 
-    def __str__(self) -> str:
+    def __repr__(self) -> str:
         """Converts this calendar system to text by simply returning its unique ID."""
         return self.id
 

pyoda_time/_system_clock.py

@@ -40,8 +40,6 @@ class SystemClock(IClock, metaclass=__SystemClockMeta):
     your application, which should only depend on the interface.
     """
 
-    instance: SystemClock
-
     def get_current_instant(self) -> Instant:
         """Gets the current time as an ``Instant``.