From ce56212d479cc6916acf57f79b3a7c6ba75c5144 Mon Sep 17 00:00:00 2001 From: Chris McEvoy <12284065+chrisimcevoy@users.noreply.github.com> Date: Thu, 6 Jun 2024 18:54:57 +0100 Subject: [PATCH] docs: misc sphinx docs tidy-ups (#165) --- Makefile | 9 ++------- docs/source/conf.py | 23 ++++++++++++++++++----- docs/source/index.rst | 4 ++-- docs/source/modules.rst | 2 +- docs/source/pyoda_time.rst | 2 +- docs/source/pyoda_time.testing.rst | 2 +- docs/source/pyoda_time.text.rst | 2 +- docs/source/pyoda_time.time_zones.rst | 2 +- pyoda_time/_calendar_system.py | 2 +- pyoda_time/_system_clock.py | 2 -- 10 files changed, 28 insertions(+), 22 deletions(-) diff --git a/Makefile b/Makefile index 16f4b18..12ad429 100644 --- a/Makefile +++ b/Makefile @@ -14,12 +14,7 @@ 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. @@ -27,4 +22,4 @@ docs.sphinx.html: # 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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 4dd88d8..7eb12f9 100644 --- a/docs/source/conf.py +++ b/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) diff --git a/docs/source/index.rst b/docs/source/index.rst index 95a86c6..8a7d713 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,10 +7,10 @@ Welcome to Pyoda Time's documentation! ====================================== .. toctree:: - :maxdepth: 2 + :maxdepth: 4 :caption: Contents: - API Reference + modules diff --git a/docs/source/modules.rst b/docs/source/modules.rst index 616659a..94d769a 100644 --- a/docs/source/modules.rst +++ b/docs/source/modules.rst @@ -2,6 +2,6 @@ pyoda_time ========== .. toctree:: - :maxdepth: 1 + :maxdepth: 4 pyoda_time diff --git a/docs/source/pyoda_time.rst b/docs/source/pyoda_time.rst index 9c51b53..019d811 100644 --- a/docs/source/pyoda_time.rst +++ b/docs/source/pyoda_time.rst @@ -5,7 +5,7 @@ Subpackages ----------- .. toctree:: - :maxdepth: 1 + :maxdepth: 4 pyoda_time.calendars pyoda_time.fields diff --git a/docs/source/pyoda_time.testing.rst b/docs/source/pyoda_time.testing.rst index 71e1a46..0c49990 100644 --- a/docs/source/pyoda_time.testing.rst +++ b/docs/source/pyoda_time.testing.rst @@ -5,7 +5,7 @@ Subpackages ----------- .. toctree:: - :maxdepth: 1 + :maxdepth: 4 pyoda_time.testing.time_zones diff --git a/docs/source/pyoda_time.text.rst b/docs/source/pyoda_time.text.rst index 94f65a9..aaf0c00 100644 --- a/docs/source/pyoda_time.text.rst +++ b/docs/source/pyoda_time.text.rst @@ -5,7 +5,7 @@ Subpackages ----------- .. toctree:: - :maxdepth: 1 + :maxdepth: 4 pyoda_time.text.patterns diff --git a/docs/source/pyoda_time.time_zones.rst b/docs/source/pyoda_time.time_zones.rst index c7101db..aabed08 100644 --- a/docs/source/pyoda_time.time_zones.rst +++ b/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 diff --git a/pyoda_time/_calendar_system.py b/pyoda_time/_calendar_system.py index a5ca8b5..d3bf586 100644 --- a/pyoda_time/_calendar_system.py +++ b/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 diff --git a/pyoda_time/_system_clock.py b/pyoda_time/_system_clock.py index 4bd9a1f..1d4d8b4 100644 --- a/pyoda_time/_system_clock.py +++ b/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``.