docs: Small improvements.

* Clean up sphinx warnings.
 * Include status in multiple locations.

Signed-off-by: Tim 'mithro' Ansell <tansell@google.com>

Makefile

@@ -25,7 +25,7 @@ README.rst: README.src.rst docs/status.rst Makefile | $(CONDA_ENV_PYTHON)
 		| sed \
 			-e's@|TAG_VERSION|@$(TAG_VERSION)@g' \
 			-e's@:ref:`Versioning Information`@`Versioning Information <docs/versioning.rst>`_@g' \
-			-e's@:ref:`Known Issues`@`Versioning Information <docs/known_issues.rst>`_@g' \
+			-e's@:ref:`Known Issues`@`Known Issues <docs/known_issues.rst>`_@g' \
 			-e's@.. warning::@*Warning*@g' \
 		> README.rst
 

README.rst

@@ -33,10 +33,14 @@ The SkyWater Open Source PDK documentation can be found at <https://skywater-pdk
    :target: https://github.com/google/skywater-pdk
    :width: 80%
 
-.. _CurrentStatus:
+.. |current-status| replace:: **Experimental Preview**
 
-Current Status - **Experimental Preview**
+.. include:: common.inc
-=========================================
+
+Current Status -- |current-status|
+==================================
+
+.. current_status_text
 
 *Warning*
    Google and SkyWater are currently treating the current content as an **experimental preview** / **alpha release**.
@@ -51,7 +55,7 @@ To get notified about future new releases of the PDK, and other important news,
 `skywater-pdk-announce mailing list <https://groups.google.com/forum/#!forum/skywater-pdk-announce>`_
 [`join link <https://groups.google.com/forum/#!forum/skywater-pdk-announce/join>`_].
 
-See both the `Versioning Information <docs/known_issues.rst>`_ section and the `SkyWater PDK GitHub issue list <https://github.com/google/skywater-pdk/issues>`_ to get more detailed information around currently known issues.
+See both the `Known Issues <docs/known_issues.rst>`_ section and the `SkyWater PDK GitHub issue list <https://github.com/google/skywater-pdk/issues>`_ to get more detailed information around currently known issues.
 
 SKY130 Process Node
 ===================

README.src.rst

@@ -1,5 +1,3 @@
-
-
 SkyWater Open Source PDK
 ========================
 
@@ -35,7 +33,7 @@ The SkyWater Open Source PDK documentation can be found at <https://skywater-pdk
    :target: https://github.com/google/skywater-pdk
    :width: 80%
 
-
+.. include:: docs/common.inc
 .. include:: docs/status.rst
 
 See both the :ref:`Known Issues` section and the `SkyWater PDK GitHub issue list <https://github.com/google/skywater-pdk/issues>`_ to get more detailed information around currently known issues.

docs/Makefile

@@ -60,3 +60,10 @@ echo: | $(CONDA_ENV_PYTHON)
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 .DEFAULT: | $(CONDA_ENV_PYTHON)
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+clean: clean-docs
+
+
+clean-docs:
+	rm -rf _build

docs/common.inc

@@ -0,0 +1 @@
+.. |current-status| replace:: **Experimental Preview**

docs/conf.py

@@ -45,6 +45,7 @@ extensions = [
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.githubpages',
+    'sphinx.ext.autosectionlabel',
     'sphinxcontrib_verilog_diagrams',
 ]
 
@@ -96,12 +97,26 @@ language = None
 # 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', 'env', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [
+    '_build',
+    'env',
+    'Thumbs.db',
+    '.DS_Store',
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
 
+# -- Options for HTML output -------------------------------------------------
+
+# Prefix each section label with the name of the document it is in, followed by
+# a colon. For example, index:Introduction for a section called Introduction
+# that appears in document index.rst. Useful for avoiding ambiguity when the
+# same section heading appears in different documents.
+#autosectionlabel_prefix_document = True
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/index.rst

@@ -1,7 +1,4 @@
-Welcome to SkyWater SKY130 PDK's documentation!
+.. include:: common.inc
-===============================================
-
-TODO: Put documentation here.
 
 .. toctree::
     :hidden:
@@ -9,9 +6,25 @@ TODO: Put documentation here.
     contributing
     code-of-conduct
 
+    status
     known_issues
     versioning
-    status
+
+
+Welcome to SkyWater SKY130 PDK's documentation!
+===============================================
+
+.. warning::
+    This documentation is currently a **work in progress**.
+
+
+.. _CurrentStatus:
+
+Current Status - |current-status|
+=================================
+
+.. include:: status.rst
+    :start-after: current_status_text
 
 
 Indices and tables

docs/known_issues.rst

@@ -1,13 +1,17 @@
-.. include:: status.rst
+.. include:: common.inc
 
-Currently Known Issues
+Known Issues
-======================
+============
 
 This section of the documentation provides a list of currently known issues in the currently released files.
 
 See also the `SkyWater PDK GitHub issue list <https://github.com/google/skywater-pdk/issues>`_ to see the latest reported issues.
 
 
+.. include:: status.rst
+    :start-after: current_status_text
+
+
 Documentation
 -------------
 

docs/status.rst

@@ -1,7 +1,9 @@
-.. _CurrentStatus:
+.. include:: common.inc
 
-Current Status - **Experimental Preview**
+Current Status -- |current-status|
-=========================================
+==================================
+
+.. current_status_text
 
 .. warning::
    Google and SkyWater are currently treating the current content as an **experimental preview** / **alpha release**.

docs/versioning.rst

@@ -1,8 +1,17 @@
+.. include:: common.inc
+
+Versioning Information
+======================
+
+Current Status
+--------------
+
+.. include:: status.rst
+    :start-after: current_status_text
+
 Version Number Format
 ---------------------
 
-
-
 Version numbers for both the PDK and the supplied libraries are fully specified by a 3-digit version number followed by a git commit count and a git commit short hash.
 
 The 3-digit-number will be tagged in the associated git repository as ``vX.Y.Z`` and the fully specified value can be found by running |git-describe|_ tool inside the correct git repository.