From 41a08351594e0ead2e71bf29dd60f7e58f69f435 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 21 Jul 2023 15:49:58 -0600 Subject: [PATCH] Re-organize documentation into top-level user/contributor categories --- doc/conf.py | 1 - doc/contributor-how-to/index.rst | 11 --- .../discussion/contributing.md | 0 doc/contributor/discussion/index.rst | 11 +++ .../discussion/pydantic-and-mypy.md | 0 .../how-to}/contribute-layers.md | 0 .../how-to}/contribute-styles.md | 0 doc/contributor/how-to/index.rst | 11 +++ .../how-to}/release-new-version.md | 0 .../how-to}/run-qgreenland.md | 0 .../how-to}/use-our-tooling.md | 0 .../how-to}/write-documentation.md | 0 doc/{ => contributor}/reference/api/index.rst | 0 doc/{ => contributor}/reference/api/models.md | 0 .../reference/api/utilities.md | 0 .../reference/architecture/configuration.md | 0 .../reference/architecture/index.rst | 0 .../reference/architecture/processing.md | 0 .../reference/architecture/storage.md | 0 doc/{ => contributor}/reference/cli/index.rst | 0 .../reference/glossary.md} | 0 doc/contributor/reference/index.rst | 14 ++++ .../reference/style-guide.md | 0 doc/index.rst | 78 +++--------------- doc/reference/glossary/index.rst | 12 --- doc/sphinx-ext/toctree_select_builder.py | 79 ------------------- doc/user-how-to/index.rst | 11 --- doc/{ => user}/discussion/about_project.md | 0 doc/user/discussion/index.rst | 17 ++++ .../how-to}/adding-data.md | 0 doc/user/how-to/index.rst | 17 ++++ doc/{user-how-to => user/how-to}/metadata.md | 0 .../how-to}/online-layers.md | 2 +- .../how-to}/troubleshooting.md | 0 .../reference/data-compatibility-guide.md | 24 +++--- .../reference/glossary.md} | 2 +- doc/user/reference/index.rst | 17 ++++ doc/{ => user}/reference/online-resources.md | 2 +- .../tutorials/analyze-ice-sheet-volume.md | 0 .../tutorials/create-print-layout.md | 0 doc/{ => user}/tutorials/get-started.md | 0 doc/user/tutorials/index.rst | 17 ++++ .../interacting-with-geospatial-data.md | 0 doc/{ => user}/tutorials/plugin-how-to.md | 0 .../tutorials/video-series-overview.md | 0 45 files changed, 131 insertions(+), 195 deletions(-) delete mode 100644 doc/contributor-how-to/index.rst rename doc/{ => contributor}/discussion/contributing.md (100%) create mode 100644 doc/contributor/discussion/index.rst rename doc/{ => contributor}/discussion/pydantic-and-mypy.md (100%) rename doc/{contributor-how-to => contributor/how-to}/contribute-layers.md (100%) rename doc/{contributor-how-to => contributor/how-to}/contribute-styles.md (100%) create mode 100644 doc/contributor/how-to/index.rst rename doc/{contributor-how-to => contributor/how-to}/release-new-version.md (100%) rename doc/{contributor-how-to => contributor/how-to}/run-qgreenland.md (100%) rename doc/{contributor-how-to => contributor/how-to}/use-our-tooling.md (100%) rename doc/{contributor-how-to => contributor/how-to}/write-documentation.md (100%) rename doc/{ => contributor}/reference/api/index.rst (100%) rename doc/{ => contributor}/reference/api/models.md (100%) rename doc/{ => contributor}/reference/api/utilities.md (100%) rename doc/{ => contributor}/reference/architecture/configuration.md (100%) rename doc/{ => contributor}/reference/architecture/index.rst (100%) rename doc/{ => contributor}/reference/architecture/processing.md (100%) rename doc/{ => contributor}/reference/architecture/storage.md (100%) rename doc/{ => contributor}/reference/cli/index.rst (100%) rename doc/{reference/glossary/contributor-glossary.md => contributor/reference/glossary.md} (100%) create mode 100644 doc/contributor/reference/index.rst rename doc/{ => contributor}/reference/style-guide.md (100%) delete mode 100644 doc/reference/glossary/index.rst delete mode 100644 doc/sphinx-ext/toctree_select_builder.py delete mode 100644 doc/user-how-to/index.rst rename doc/{ => user}/discussion/about_project.md (100%) create mode 100644 doc/user/discussion/index.rst rename doc/{user-how-to => user/how-to}/adding-data.md (100%) create mode 100644 doc/user/how-to/index.rst rename doc/{user-how-to => user/how-to}/metadata.md (100%) rename doc/{user-how-to => user/how-to}/online-layers.md (98%) rename doc/{user-how-to => user/how-to}/troubleshooting.md (100%) rename doc/{ => user}/reference/data-compatibility-guide.md (81%) rename doc/{reference/glossary/user-glossary.md => user/reference/glossary.md} (99%) create mode 100644 doc/user/reference/index.rst rename doc/{ => user}/reference/online-resources.md (97%) rename doc/{ => user}/tutorials/analyze-ice-sheet-volume.md (100%) rename doc/{ => user}/tutorials/create-print-layout.md (100%) rename doc/{ => user}/tutorials/get-started.md (100%) create mode 100644 doc/user/tutorials/index.rst rename doc/{ => user}/tutorials/interacting-with-geospatial-data.md (100%) rename doc/{ => user}/tutorials/plugin-how-to.md (100%) rename doc/{ => user}/tutorials/video-series-overview.md (100%) diff --git a/doc/conf.py b/doc/conf.py index 3fc20b581..e0686e700 100644 --- 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 deleted file mode 100644 index 0fb229fcc..000000000 --- a/doc/contributor-how-to/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _contributor-how-to: - -========================= -Contributor how-to guides -========================= - -.. toctree:: - :maxdepth: 1 - :glob: - - ./* diff --git a/doc/discussion/contributing.md b/doc/contributor/discussion/contributing.md similarity index 100% rename from doc/discussion/contributing.md rename to doc/contributor/discussion/contributing.md diff --git a/doc/contributor/discussion/index.rst b/doc/contributor/discussion/index.rst new file mode 100644 index 000000000..5e061da7f --- /dev/null +++ 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 b/doc/contributor/discussion/pydantic-and-mypy.md similarity index 100% rename from doc/discussion/pydantic-and-mypy.md rename to doc/contributor/discussion/pydantic-and-mypy.md diff --git a/doc/contributor-how-to/contribute-layers.md b/doc/contributor/how-to/contribute-layers.md similarity index 100% rename from doc/contributor-how-to/contribute-layers.md rename to doc/contributor/how-to/contribute-layers.md diff --git a/doc/contributor-how-to/contribute-styles.md b/doc/contributor/how-to/contribute-styles.md similarity index 100% rename from doc/contributor-how-to/contribute-styles.md rename to doc/contributor/how-to/contribute-styles.md diff --git a/doc/contributor/how-to/index.rst b/doc/contributor/how-to/index.rst new file mode 100644 index 000000000..099ffcaef --- /dev/null +++ b/doc/contributor/how-to/index.rst @@ -0,0 +1,11 @@ +.. _contributor-how-to: + +============= +How-to guides +============= + +.. toctree:: + :maxdepth: 1 + :glob: + + ./* diff --git a/doc/contributor-how-to/release-new-version.md b/doc/contributor/how-to/release-new-version.md similarity index 100% rename from doc/contributor-how-to/release-new-version.md rename to doc/contributor/how-to/release-new-version.md diff --git a/doc/contributor-how-to/run-qgreenland.md b/doc/contributor/how-to/run-qgreenland.md similarity index 100% rename from doc/contributor-how-to/run-qgreenland.md rename to doc/contributor/how-to/run-qgreenland.md diff --git a/doc/contributor-how-to/use-our-tooling.md b/doc/contributor/how-to/use-our-tooling.md similarity index 100% rename from doc/contributor-how-to/use-our-tooling.md rename to doc/contributor/how-to/use-our-tooling.md diff --git a/doc/contributor-how-to/write-documentation.md b/doc/contributor/how-to/write-documentation.md similarity index 100% rename from doc/contributor-how-to/write-documentation.md rename to doc/contributor/how-to/write-documentation.md diff --git a/doc/reference/api/index.rst b/doc/contributor/reference/api/index.rst similarity index 100% rename from doc/reference/api/index.rst rename to doc/contributor/reference/api/index.rst diff --git a/doc/reference/api/models.md b/doc/contributor/reference/api/models.md similarity index 100% rename from doc/reference/api/models.md rename to doc/contributor/reference/api/models.md diff --git a/doc/reference/api/utilities.md b/doc/contributor/reference/api/utilities.md similarity index 100% rename from doc/reference/api/utilities.md rename to doc/contributor/reference/api/utilities.md diff --git a/doc/reference/architecture/configuration.md b/doc/contributor/reference/architecture/configuration.md similarity index 100% rename from doc/reference/architecture/configuration.md rename to doc/contributor/reference/architecture/configuration.md diff --git a/doc/reference/architecture/index.rst b/doc/contributor/reference/architecture/index.rst similarity index 100% rename from doc/reference/architecture/index.rst rename to doc/contributor/reference/architecture/index.rst diff --git a/doc/reference/architecture/processing.md b/doc/contributor/reference/architecture/processing.md similarity index 100% rename from doc/reference/architecture/processing.md rename to doc/contributor/reference/architecture/processing.md diff --git a/doc/reference/architecture/storage.md b/doc/contributor/reference/architecture/storage.md similarity index 100% rename from doc/reference/architecture/storage.md rename to doc/contributor/reference/architecture/storage.md diff --git a/doc/reference/cli/index.rst b/doc/contributor/reference/cli/index.rst similarity index 100% rename from doc/reference/cli/index.rst rename to doc/contributor/reference/cli/index.rst diff --git a/doc/reference/glossary/contributor-glossary.md b/doc/contributor/reference/glossary.md similarity index 100% rename from doc/reference/glossary/contributor-glossary.md rename to doc/contributor/reference/glossary.md diff --git a/doc/contributor/reference/index.rst b/doc/contributor/reference/index.rst new file mode 100644 index 000000000..201f41878 --- /dev/null +++ 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 b/doc/contributor/reference/style-guide.md similarity index 100% rename from doc/reference/style-guide.md rename to doc/contributor/reference/style-guide.md diff --git a/doc/index.rst b/doc/index.rst index fd7935b2b..a0417d75c 100644 --- 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 deleted file mode 100644 index 152c06c75..000000000 --- a/doc/reference/glossary/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _glossary-reference: - -======== -Glossary -======== - -.. toctree:: - :maxdepth: 1 - :glob: - - ./user-glossary.md - ./contributor-glossary.md diff --git a/doc/sphinx-ext/toctree_select_builder.py b/doc/sphinx-ext/toctree_select_builder.py deleted file mode 100644 index 9c9f21238..000000000 --- a/doc/sphinx-ext/toctree_select_builder.py +++ /dev/null @@ -1,79 +0,0 @@ -"""Support a `toctree-select-builder` directive. - -This new directive enables a special type of toctree which is filtered based on the -current builder. - -Inspired by / based on . -""" -import re - -from sphinx.directives.other import TocTree -from sphinx.util import logging - -logger = logging.getLogger(__name__) - - -def setup(app): - app.add_directive("toctree-select-builder", TocTreeSelectBuilder) - return {"version": "1.0.0"} - - -class TocTreeSelectBuilder(TocTree): - """A version of `toctree` directive which supports selecting items by builder name. - - We filter the content of the directive and then call the super's version of run. - Any table of prefixed with a string will be included only if the builder name - matches that string. If the builder name is `html`, the following toc entries will - have the following results: - - * `foo`: included because there is no prefix - * `:html:bar`: included because the prefix matches the builder name - * `:baz:qux`: excluded because the prefix mismatches the builder name - """ - - prefixPattern = re.compile("^\s*:(.+):(.+)$") - - def filter_entries(self, entries): - """Discard entries whose prefix mismatches the current builder. - - Prefixes are removed in the process. - """ - valid_prefixes = ["html", "latex"] - builder_name = self.env.app.builder.name - - selected = [] - for e in entries: - m = self.prefixPattern.match(e) - - # Keep the whole entry if no prefix found. Move on to the next entry. - if m is None: - selected.append(e) - continue - - prefix = m.groups()[0] - value = m.groups()[1] - - if prefix not in valid_prefixes: - msg = ( - f"Entry '{e}' from toc named '{self.options['name']}'" - f" has invalid {prefix=}; must be one of {valid_prefixes=} " - ) - logger.error(msg) - raise RuntimeError(msg) - - # If there's a prefix, keep only if it matches builder name - if prefix == builder_name: - # Keep the value but not the prefix - selected.append(value) - - else: - logger.warning( - f"Discarding entry '{e}' from toc named '{self.options['name']}':" - f" {prefix=} does not match {builder_name=}" - ) - - return selected - - def run(self): - self.content = self.filter_entries(self.content) - return super().run() diff --git a/doc/user-how-to/index.rst b/doc/user-how-to/index.rst deleted file mode 100644 index e2a9bc2c6..000000000 --- a/doc/user-how-to/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _user-how-to: - -================== -User how-to guides -================== - -.. toctree:: - :maxdepth: 1 - :glob: - - ./* diff --git a/doc/discussion/about_project.md b/doc/user/discussion/about_project.md similarity index 100% rename from doc/discussion/about_project.md rename to doc/user/discussion/about_project.md diff --git a/doc/user/discussion/index.rst b/doc/user/discussion/index.rst new file mode 100644 index 000000000..32e687c7c --- /dev/null +++ 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 b/doc/user/how-to/adding-data.md similarity index 100% rename from doc/user-how-to/adding-data.md rename to doc/user/how-to/adding-data.md diff --git a/doc/user/how-to/index.rst b/doc/user/how-to/index.rst new file mode 100644 index 000000000..863c512d8 --- /dev/null +++ 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 b/doc/user/how-to/metadata.md similarity index 100% rename from doc/user-how-to/metadata.md rename to doc/user/how-to/metadata.md diff --git a/doc/user-how-to/online-layers.md b/doc/user/how-to/online-layers.md similarity index 98% rename from doc/user-how-to/online-layers.md rename to doc/user/how-to/online-layers.md index a90fbdb60..7c57ea796 100644 --- a/doc/user-how-to/online-layers.md +++ b/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 b/doc/user/how-to/troubleshooting.md similarity index 100% rename from doc/user-how-to/troubleshooting.md rename to doc/user/how-to/troubleshooting.md diff --git a/doc/reference/data-compatibility-guide.md b/doc/user/reference/data-compatibility-guide.md similarity index 81% rename from doc/reference/data-compatibility-guide.md rename to doc/user/reference/data-compatibility-guide.md index debca28d8..68036f297 100644 --- a/doc/reference/data-compatibility-guide.md +++ b/doc/user/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 b/doc/user/reference/glossary.md similarity index 99% rename from doc/reference/glossary/user-glossary.md rename to doc/user/reference/glossary.md index 832f8cd4c..6b77227be 100644 --- a/doc/reference/glossary/user-glossary.md +++ b/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 new file mode 100644 index 000000000..0f93093d1 --- /dev/null +++ b/doc/user/reference/index.rst @@ -0,0 +1,17 @@ +.. _user-reference: + + +.. raw:: latex + + \part{Reference} + + +========= +Reference +========= + +.. toctree:: + :maxdepth: 1 + :glob: + + ./* diff --git a/doc/reference/online-resources.md b/doc/user/reference/online-resources.md similarity index 97% rename from doc/reference/online-resources.md rename to doc/user/reference/online-resources.md index bfc09854a..cd41fec55 100644 --- a/doc/reference/online-resources.md +++ b/doc/user/reference/online-resources.md @@ -7,7 +7,7 @@ Map Service (WMS)](https://www.ogc.org/standards/wms), [Web Feature Service potentially useful resources that QGIS can connect to to provide layers via the internet. -See the [How to add an online layer to QGIS](/user-how-to/online-layers.md) page +See the [How to add an online layer to QGIS](/user/how-to/online-layers.md) page for information on how to utilize these resources. * [The National Snow and Ice Data Center diff --git a/doc/tutorials/analyze-ice-sheet-volume.md b/doc/user/tutorials/analyze-ice-sheet-volume.md similarity index 100% rename from doc/tutorials/analyze-ice-sheet-volume.md rename to doc/user/tutorials/analyze-ice-sheet-volume.md diff --git a/doc/tutorials/create-print-layout.md b/doc/user/tutorials/create-print-layout.md similarity index 100% rename from doc/tutorials/create-print-layout.md rename to doc/user/tutorials/create-print-layout.md diff --git a/doc/tutorials/get-started.md b/doc/user/tutorials/get-started.md similarity index 100% rename from doc/tutorials/get-started.md rename to doc/user/tutorials/get-started.md diff --git a/doc/user/tutorials/index.rst b/doc/user/tutorials/index.rst new file mode 100644 index 000000000..42d5a4afe --- /dev/null +++ b/doc/user/tutorials/index.rst @@ -0,0 +1,17 @@ +.. _user-tutorials: + + +.. raw:: latex + + \part{Tutorials} + + +========= +Tutorials +========= + +.. toctree:: + :maxdepth: 1 + :glob: + + ./* diff --git a/doc/tutorials/interacting-with-geospatial-data.md b/doc/user/tutorials/interacting-with-geospatial-data.md similarity index 100% rename from doc/tutorials/interacting-with-geospatial-data.md rename to doc/user/tutorials/interacting-with-geospatial-data.md diff --git a/doc/tutorials/plugin-how-to.md b/doc/user/tutorials/plugin-how-to.md similarity index 100% rename from doc/tutorials/plugin-how-to.md rename to doc/user/tutorials/plugin-how-to.md diff --git a/doc/tutorials/video-series-overview.md b/doc/user/tutorials/video-series-overview.md similarity index 100% rename from doc/tutorials/video-series-overview.md rename to doc/user/tutorials/video-series-overview.md