Merge pull request #692 from nsidc/docs-by-user-contributor-split

Split docs by user/contributor at top level [redo]
nsidc · Jul 21, 2023 · 88d16a7 · 88d16a7
2 parents 4fee161 + d1ecc40
commit 88d16a7
Show file tree

Hide file tree

Showing 46 changed files with 134 additions and 212 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -47,7 +47,6 @@
     "sphinx_selective_exclude.eager_only",
     "sphinx_selective_exclude.search_auto_exclude",
     "sphinx_selective_exclude.modindex_exclude",
-    "toctree_select_builder",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/doc/contributor-how-to/index.rst b/doc/contributor-how-to/index.rst
diff --git a/doc/discussion/contributing.md → doc/contributor/discussion/contributing.md b/doc/discussion/contributing.md → doc/contributor/discussion/contributing.md
diff --git a/doc/contributor/discussion/index.rst b/doc/contributor/discussion/index.rst
@@ -0,0 +1,11 @@
+.. _contributor-discussion:
+
+==========
+Discussion
+==========
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    ./*
diff --git a/doc/discussion/pydantic-and-mypy.md → ...ntributor/discussion/pydantic-and-mypy.md b/doc/discussion/pydantic-and-mypy.md → ...ntributor/discussion/pydantic-and-mypy.md
diff --git a/doc/contributor-how-to/contribute-layers.md → doc/contributor/how-to/contribute-layers.md b/doc/contributor-how-to/contribute-layers.md → doc/contributor/how-to/contribute-layers.md
diff --git a/doc/contributor-how-to/contribute-styles.md → doc/contributor/how-to/contribute-styles.md b/doc/contributor-how-to/contribute-styles.md → doc/contributor/how-to/contribute-styles.md
diff --git a/doc/contributor/how-to/index.rst b/doc/contributor/how-to/index.rst
@@ -0,0 +1,11 @@
+.. _contributor-how-to:
+
+=============
+How-to guides
+=============
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    ./*
diff --git a/...contributor-how-to/release-new-version.md → ...contributor/how-to/release-new-version.md b/...contributor-how-to/release-new-version.md → ...contributor/how-to/release-new-version.md
diff --git a/doc/contributor-how-to/run-qgreenland.md → doc/contributor/how-to/run-qgreenland.md b/doc/contributor-how-to/run-qgreenland.md → doc/contributor/how-to/run-qgreenland.md
diff --git a/doc/contributor-how-to/use-our-tooling.md → doc/contributor/how-to/use-our-tooling.md b/doc/contributor-how-to/use-our-tooling.md → doc/contributor/how-to/use-our-tooling.md
diff --git a/...contributor-how-to/write-documentation.md → ...contributor/how-to/write-documentation.md b/...contributor-how-to/write-documentation.md → ...contributor/how-to/write-documentation.md
@@ -53,21 +53,6 @@ one might intuitively expect. Specifically, it isn't capable of creating conditi
 filtered `toctrees`. Because of this insufficiency, we're employing two nonstandard
 methods in `doc/index.rst` to deselect items from PDF docs:
 
-* Our custom `.. toctree-select-builder::` directive, defined in
-  `doc/sphinx-ext/toctree_select_builder.py`, is a customized `toctree` directive which
-  enables filtering its contents. If a prefix is present, that entry will only be kept
-  if the prefix matches the name of the current builder.
-
-  ```rst
-  .. toctree-select-builder::
-      :name: Mixed content
-      :caption: Mixed content
-
-      always/shown/document
-      :html:html/only/document
-      :latex:pdf/only/document
-  ```
-
 * The package
   [sphinx-selective-exclude](https://pypi.org/project/sphinx-selective-exclude/)
   enhances the behavior of `.. only::` to more intuitively select content during the

diff --git a/doc/reference/api/index.rst → doc/contributor/reference/api/index.rst b/doc/reference/api/index.rst → doc/contributor/reference/api/index.rst
diff --git a/doc/reference/api/models.md → doc/contributor/reference/api/models.md b/doc/reference/api/models.md → doc/contributor/reference/api/models.md
diff --git a/doc/reference/api/utilities.md → doc/contributor/reference/api/utilities.md b/doc/reference/api/utilities.md → doc/contributor/reference/api/utilities.md
diff --git a/doc/reference/architecture/configuration.md → ...r/reference/architecture/configuration.md b/doc/reference/architecture/configuration.md → ...r/reference/architecture/configuration.md
diff --git a/doc/reference/architecture/index.rst → ...tributor/reference/architecture/index.rst b/doc/reference/architecture/index.rst → ...tributor/reference/architecture/index.rst
diff --git a/doc/reference/architecture/processing.md → ...utor/reference/architecture/processing.md b/doc/reference/architecture/processing.md → ...utor/reference/architecture/processing.md
diff --git a/doc/reference/architecture/storage.md → ...ributor/reference/architecture/storage.md b/doc/reference/architecture/storage.md → ...ributor/reference/architecture/storage.md
diff --git a/doc/reference/cli/index.rst → doc/contributor/reference/cli/index.rst b/doc/reference/cli/index.rst → doc/contributor/reference/cli/index.rst
diff --git a/...eference/glossary/contributor-glossary.md → doc/contributor/reference/glossary.md b/...eference/glossary/contributor-glossary.md → doc/contributor/reference/glossary.md
diff --git a/doc/contributor/reference/index.rst b/doc/contributor/reference/index.rst
@@ -0,0 +1,14 @@
+.. _contributor-reference:
+
+=========
+Reference
+=========
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    ./architecture/index
+    ./api/index
+    ./cli/index
+    ./*
diff --git a/doc/reference/style-guide.md → doc/contributor/reference/style-guide.md b/doc/reference/style-guide.md → doc/contributor/reference/style-guide.md
diff --git a/doc/index.rst b/doc/index.rst
@@ -23,87 +23,33 @@ QGreenland Documentation
     acknowledgements.md
 
 
-.. raw:: latex
-
-    \part{Tutorials}
-
-
 .. toctree::
-    :name: Tutorials
-    :caption: Tutorials
-    :maxdepth: 1
-    :glob:
+    :name: User_Documentation
+    :caption: User Documentation
     :hidden:
 
-    tutorials/get-started.md
-    tutorials/video-series-overview.md
-    tutorials/*
-
-
-.. raw:: latex
-
-    \part{How-to}
-
-
-.. toctree-select-builder::
-    :name: How-to
-    :caption: How-to
-    :maxdepth: 1
-    :hidden:
-
-    user-how-to/index
-    :html:contributor-how-to/index
-
-
-.. raw:: latex
-
-    \part{Reference}
-
-
-.. toctree::
-    :name: User_Reference
-    :caption: User Reference
-    :maxdepth: 1
-    :hidden:
-
-    reference/glossary/index
-    reference/data-compatibility-guide.md
-    reference/online-resources.md
+    user/tutorials/index
+    user/how-to/index
+    user/reference/index
+    user/discussion/index
 
 
 .. only:: html
 
     .. toctree::
-        :name: Contributor_Reference
-        :caption: Contributor Reference
+        :name: Contributor_Documentation
+        :caption: Contributor Documentation
         :maxdepth: 1
         :hidden:
 
-        reference/architecture/index
-        reference/api/index
-        reference/cli/index
-        reference/style-guide.md
-
-
-.. raw:: latex
-
-    \part{Discussion topics}
+        contributor/how-to/index
+        contributor/reference/index
+        contributor/discussion/index
 
 
-.. toctree::
-    :name: Discussion topics
-    :caption: Discussion topics
-    :maxdepth: 1
-    :glob:
-    :hidden:
-
-    discussion/*
-
-
-.. only:: html
-
     .. include:: what_is_qgr.md
         :parser: myst_parser.sphinx_
 
+
     .. include:: citing.md
         :parser: myst_parser.sphinx_
diff --git a/doc/reference/glossary/index.rst b/doc/reference/glossary/index.rst
diff --git a/doc/sphinx-ext/toctree_select_builder.py b/doc/sphinx-ext/toctree_select_builder.py
diff --git a/doc/user-how-to/index.rst b/doc/user-how-to/index.rst
diff --git a/doc/discussion/about_project.md → doc/user/discussion/about_project.md b/doc/discussion/about_project.md → doc/user/discussion/about_project.md
diff --git a/doc/user/discussion/index.rst b/doc/user/discussion/index.rst
@@ -0,0 +1,17 @@
+.. _user-discussion:
+
+
+.. raw:: latex
+
+    \part{Discussion topics}
+
+
+==========
+Discussion
+==========
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    ./*
diff --git a/doc/user-how-to/adding-data.md → doc/user/how-to/adding-data.md b/doc/user-how-to/adding-data.md → doc/user/how-to/adding-data.md
diff --git a/doc/user/how-to/index.rst b/doc/user/how-to/index.rst
@@ -0,0 +1,17 @@
+.. _user-how-to:
+
+
+.. raw:: latex
+
+    \part{How-to}
+
+
+=============
+How-to guides
+=============
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    ./*
diff --git a/doc/user-how-to/metadata.md → doc/user/how-to/metadata.md b/doc/user-how-to/metadata.md → doc/user/how-to/metadata.md
diff --git a/doc/user-how-to/online-layers.md → doc/user/how-to/online-layers.md b/doc/user-how-to/online-layers.md → doc/user/how-to/online-layers.md
@@ -40,7 +40,7 @@ information about NSIDC’s web map services is available here:
 [https://nsidc.org/map-services/geospatial-map-services](https://nsidc.org/map-services/geospatial-map-services).
 
 For additional online resources, see the [Online layers
-reference](/reference/online-resources.md) page.
+reference](/user/reference/online-resources.md) page.
 ```
 
 ![wms_connection_details](/_images/wms_connection_details.png)

diff --git a/doc/user-how-to/troubleshooting.md → doc/user/how-to/troubleshooting.md b/doc/user-how-to/troubleshooting.md → doc/user/how-to/troubleshooting.md
diff --git a/doc/reference/data-compatibility-guide.md → ...ser/reference/data-compatibility-guide.md b/doc/reference/data-compatibility-guide.md → ...ser/reference/data-compatibility-guide.md
@@ -1,4 +1,4 @@
-# QGreenland Dataset Compatibility Guide
+# Dataset Compatibility Guide
 
 While QGreenland provides a curated base package of data on a variety of topics,
 the options for adding additional data are nearly unlimited. We offer different
@@ -30,20 +30,20 @@ to the public QGreenland data package, please note the following:
 
 ## Contributing datasets to QGreenland via GitHub for inclusion in future releases
 
-Follow the instructions found in our {doc}`/discussion/contributing`
-guidelines. The QGreenland source code defines “processing pipelines”, which,
-when executed on a server or a user’s computer, fetch data from its original
-source location, transform it (reproject, reformat, subset, resample, etc.) as
-needed, and finally compile these data into a zipped QGreenland QGIS
-project. Contributors may customize, re-use, or add to our processing pipelines
-to support their new layer, and when their changes are ready, submit a [Pull
+Follow the instructions found in our {doc}`/contributor/discussion/contributing`
+guidelines. The QGreenland source code defines “processing pipelines”, which, when
+executed on a server or a user’s computer, fetch data from its original source location,
+transform it (reproject, reformat, subset, resample, etc.) as needed, and finally
+compile these data into a zipped QGreenland QGIS project. Contributors may customize,
+re-use, or add to our processing pipelines to support their new layer, and when their
+changes are ready, submit a [Pull
 Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
 to contribute valuable changes back to the QGreenland project.
 
-As of QGreenland v2.0.0, we support editing of dataset metadata, QGIS styles,
-and data processing steps via simple Python-based configuration that is easy to
-learn. See the {doc}`/reference/architecture/configuration` reference page for
-more information.
+As of QGreenland v2.0.0, we support editing of dataset metadata, QGIS styles, and data
+processing steps via simple Python-based configuration that is easy to learn. See the
+{doc}`/contributor/reference/architecture/configuration` reference page for more
+information.
 
    * Ensure that all outputs of QGreenland processing pipelines are in EPSG:3413
      coordinate reference system.

diff --git a/doc/reference/glossary/user-glossary.md → doc/user/reference/glossary.md b/doc/reference/glossary/user-glossary.md → doc/user/reference/glossary.md
@@ -1,4 +1,4 @@
-# User Glossary
+# Glossary
 
 A "user" is someone who uses QGreenland in QGIS.
 

diff --git a/doc/user/reference/index.rst b/doc/user/reference/index.rst
@@ -0,0 +1,17 @@
+.. _user-reference:
+
+
+.. raw:: latex
+
+    \part{Reference}
+
+
+=========
+Reference
+=========
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    ./*