Merge pull request #2349 from Parcels-code/documentation-structure-v4

Change folder structure and navigation to highlight pages for: getting started, user guide, development, and community

Author: reint-fischer

docs/_static/LAdiag-logo.svg

@@ -1,21 +1,107 @@
 # Community
 
-These sections contain documentation relevant to the Parcels community.
-See the sections in the primary sidebar and below to explore.
+```{toctree}
+:caption: CLAM Community
+:maxdepth: 1
+:hidden:
+
+Website <https://clam-community.github.io/>
+```
 
 ```{toctree}
-:caption: User documentation
+:caption: GitHub
 :maxdepth: 1
+:hidden:
 
-contributing
-Versioning Policy <policies>
-Release Notes <https://github.com/Parcels-code/Parcels/releases>
-Parcels v4.0 Migration Guide <v4-migration>
+Discussions <https://github.com/Parcels-code/parcels/discussions>
+Issues <https://github.com/Parcels-code/parcels/issues>
 ```
 
 ```{toctree}
-:caption: Maintainer documentation
+:caption: Community examples
 :maxdepth: 1
+:hidden:
+
+Repository <https://github.com/Parcels-code/parcels_contributions>
+```
+
+Parcels users and developers interact in a vibrant community on a few different platforms. Check out the cards below to see how you can interact with us.
+
+`````{grid} 1 2 2 2
+:gutter: 4
+:padding: 2 2 0 0
+:class-container: sd-text-center
+
+````{grid-item-card} CLAM Community on Zulip
+:img-top: https://raw.githubusercontent.com/CLAM-community/CLAM-community.github.io/ca1b93cb79410f7ffbbca7ae6860c5d5e0430d31/docs/assets/branding/svg/clam-full-white-buffer.svg
+:shadow: md
+
+If you are doing any kind of Lagrangian modelling and/or analysis check out the CLAM (Computational Lagrangian Analysis and Modelling) Community
+
+```{image} https://img.shields.io/badge/Zulip-50ADFF?style=for-the-badge&logo=Zulip&logoColor=white
+:width: 30%
+:target: https://clam-community.zulipchat.com/
+```
+
++++
+
+```{button-link} https://clam-community.github.io/
+:color: secondary
+:expand:
+
+To the CLAM website
+```
+````
+````{grid-item-card} GitHub
+:img-top: ../_static/github-logo.svg
+:shadow: md
+
+If you need more help with Parcels, try the Discussions page on **GitHub**. If you think you found a bug, please feel free to file an Issue.
+
++++
+
+```{button-link} https://github.com/Parcels-code/parcels/discussions
+:color: secondary
+:expand:
+
+Ask a question in the Discussions
+```
+```{button-link} https://github.com/Parcels-code/parcels/issues
+:color: secondary
+:expand:
+
+Report a bug with an Issue
+```
+````
+````{grid-item-card} Sharing user code
+:shadow: md
+
+Curious to see if someone has already written the custom `Kernel` you are thinking of or runs **Parcels** with the same hydrodynamic data? Check out the parcels_contributions repository and share examples with other users!
+
++++
+
+```{button-link} https://github.com/Parcels-code/parcels_contributions
+:click-parent:
+:color: secondary
+:expand:
+
+Share custom Parcels code
+```
+````
+````{grid-item-card} Lagrangian Diagnostics
+:img-top: ../_static/LAdiag-logo.svg
+:shadow: md
+
+Are you interested in advanced analysis and diagnostics of Parcels output or Lagrangian trajectories in general? The Lagrangian Diagnostics project provides code and descriptions of different analyses.
+
++++
+
+```{button-link} https://github.com/Parcels-code/Lagrangian_diags
+:click-parent:
+:color: secondary
+:expand:
 
-maintainer
+Visit Lagrangian Diagnostics
 ```
+````
+`````

docs/_static/clam-full-white-buffer.svg

@@ -40,6 +40,7 @@
     "nbsphinx",
     "numpydoc",
     "sphinxcontrib.mermaid",
+    "sphinx_design",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -113,7 +114,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build", "**.ipynb_checkpoints"]
+exclude_patterns = ["_build", "**.ipynb_checkpoints", "user_guide/examples_v3"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -205,6 +206,8 @@
         }
     ],
     "announcement": "WARNING: This documentation is built for v4 of Parcels, which is unreleased and in active development. Use the version switcher in the bottom right to select your version of Parcels, or see <a href='https://docs.parcels-code.org/'>stable docs</a>.",
+    "header_links_before_dropdown": 8,
+    "navbar_align": "left",
 }
 
 html_context = {
@@ -520,3 +523,8 @@ def linkcode_resolve(domain, info):
 
 # If false, no index is generated.
 # epub_use_index = True
+
+# -- Options for MyST parser ----------------------------------------------
+myst_heading_anchors = 3
+
+myst_enable_extensions = ["substitution"]

docs/_static/github-logo.svg

@@ -0,0 +1,20 @@
+# Documentation Notes
+
+## Vision
+
+We believe a clear documentation is important to community building, reproducibility, and transparency in our open-source project. To make it easier to write our documentation in a consistent way, here we outline a brief vision for our documentation based heavily on a few common resources.
+
+```{note}
+TODO: outline functions of the documentation based on resources
+```
+
+### Resources
+
+- [Divio Documentation System](https://docs.divio.com/documentation-system/)
+- [PyOpenSci Documentation Guide](https://www.pyopensci.org/python-package-guide/documentation/index.html#)
+- [Write the Docs Guide](https://www.writethedocs.org/guide/)
+- [NumPy Documentation Article](https://labs.quansight.org/blog/2020/03/documentation-as-a-way-to-build-community)
+
+## Style guide
+
+- Write documentation in first person plural ("we"). In our open source code, tutorials and guides can be written by any developer or user, so the documentation teaches all of us how to do something with Parcels.