docs: Small improvements.
* Clean up sphinx warnings.
* Include status in multiple locations.
Signed-off-by: Tim 'mithro' Ansell <tansell@google.com>
diff --git a/Makefile b/Makefile
index 648dea6..4f37195 100644
--- a/Makefile
+++ b/Makefile
@@ -25,7 +25,7 @@
| 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
diff --git a/README.rst b/README.rst
index 6c84d61..417d077 100644
--- a/README.rst
+++ b/README.rst
@@ -33,10 +33,14 @@
: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 @@
`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
===================
diff --git a/README.src.rst b/README.src.rst
index 70e8e42..80ab13a 100644
--- a/README.src.rst
+++ b/README.src.rst
@@ -1,5 +1,3 @@
-
-
SkyWater Open Source PDK
========================
@@ -35,7 +33,7 @@
: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.
diff --git a/docs/Makefile b/docs/Makefile
index 6fd5945..8e28876 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -60,3 +60,10 @@
# "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
diff --git a/docs/common.inc b/docs/common.inc
new file mode 100644
index 0000000..ad0745c
--- /dev/null
+++ b/docs/common.inc
@@ -0,0 +1 @@
+.. |current-status| replace:: **Experimental Preview**
diff --git a/docs/conf.py b/docs/conf.py
index 455b579..3125711 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -45,6 +45,7 @@
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
'sphinx.ext.githubpages',
+ 'sphinx.ext.autosectionlabel',
'sphinxcontrib_verilog_diagrams',
]
@@ -96,7 +97,12 @@
# 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
@@ -104,6 +110,15 @@
# -- 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
# a list of builtin themes.
#
diff --git a/docs/index.rst b/docs/index.rst
index 1be3b4f..d12add8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,7 +1,4 @@
-Welcome to SkyWater SKY130 PDK's documentation!
-===============================================
-
-TODO: Put documentation here.
+.. include:: common.inc
.. toctree::
:hidden:
@@ -9,9 +6,25 @@
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
diff --git a/docs/known_issues.rst b/docs/known_issues.rst
index b3ce955..d6bf6c0 100644
--- a/docs/known_issues.rst
+++ b/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
-------------
diff --git a/docs/status.rst b/docs/status.rst
index 4f63e89..a00068e 100644
--- a/docs/status.rst
+++ b/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**.
diff --git a/docs/versioning.rst b/docs/versioning.rst
index 503f8b3..3b65446 100644
--- a/docs/versioning.rst
+++ b/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.
