Skip to content

Commit

Permalink
Split docs contrib docs into several files.
Browse files Browse the repository at this point in the history
  • Loading branch information
@swainn
swainn committed Jan 10, 2025
1 parent 63e7285 commit 37ad9e1
Show file tree
Hide file tree
Showing 7 changed files with 262 additions and 167 deletions.
12 changes: 6 additions & 6 deletions docs/contribute/code.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Contributing Code
Getting Started Tutorial
========================

Use this step-by-step guide to to guide you through the process of contributing to the Tethys Platform. It covers essential topics and initial steps to get you up and running quickly.
Use this step-by-step guide to guide you through the process of contributing to the Tethys Platform. It covers essential topics and initial steps to get you up and running quickly.

.. toctree::
:maxdepth: 1
Expand All @@ -29,7 +29,7 @@ Use these instructions to setup a new development environment for modifying Teth
Development Process
===================

This section describes the development process used for managing code contributions to Tethys Platform. It provides a a high-level description on common development activities like creating a fork of the repository, making changes on a feature branch, and submitting a pull request for review.
Learn about the development process used for managing code contributions to Tethys Platform. This guide provides a high-level description of common development activities like creating a fork of the repository, making changes on a feature branch, and submitting a pull request for review.

.. toctree::
:maxdepth: 1
Expand All @@ -39,7 +39,7 @@ This section describes the development process used for managing code contributi
Managing Issues
===============

This section explains how Issues are used to track bugs, feature requests, and other tasks for the Tethys Platform, and how they facilitate discussion, planning, and task assignment. It also highlights the need to reference relevant issues in pull requests and the importance of labeling issues for better categorization and prioritization.
Understand how Issues are used to track bugs, feature requests, and other tasks for Tethys Platform, and how they facilitate discussion, planning, and task assignment. This guide highlights the need to reference relevant issues in pull requests and the importance of labeling issues for better categorization and prioritization.

.. toctree::
:maxdepth: 1
Expand All @@ -49,7 +49,7 @@ This section explains how Issues are used to track bugs, feature requests, and o
Coding Principles
=================

This section provides high-level explanations of the design, implementation, and motivations of various parts of Tethys Platform. It best used as a primer for understanding specific areas of the code you plan to work on. For instance, if you are interested in adding a new backend for the Tethys Jobs API, you should review the Tethys Jobs documentation to learn how the current backends are implemented.
Learn the high-level explanations of the design, implementation, and motivations of various parts of Tethys Platform. This guide is best used as a primer for understanding specific areas of the code you plan to work on. For instance, if you are interested in adding a new backend for the Tethys Jobs API, you should review the Tethys Jobs documentation to learn how the current backends are implemented.

.. toctree::
:maxdepth: 2
Expand All @@ -59,7 +59,7 @@ This section provides high-level explanations of the design, implementation, and
Maintain Dependencies
=====================

This section provides instructions on managing and updating project dependencies. It includes information on maintaining Tethys maintained dependencies, like Tethys Dataset Services, updating Tethys to be compatible with new versions of third-party dependencies, and maintaining the Conda-Forge packages for third-party dependencies.
Learn how to update and manage third party dependencies of Tethys Platform. This guide includes information on maintaining Tethys maintained dependencies, like Tethys Dataset Services, updating Tethys to be compatible with new versions of third-party dependencies, and maintaining the Conda-Forge packages for third-party dependencies.

.. toctree::
:maxdepth: 1
Expand All @@ -69,7 +69,7 @@ This section provides instructions on managing and updating project dependencies
Deploying New Versions
======================

This section describes the process of releasing new versions of the Tethys Platform. It includes steps for updating version numbers, preparing the documentation for a new version, and ensuring that all necessary components are properly built and deployed.
Learn the process of releasing new versions of the Tethys Platform. This guide includes steps for updating version numbers, preparing the documentation for a new version, and ensuring that all necessary components are properly built and deployed.

.. toctree::
:maxdepth: 1
Expand Down
192 changes: 31 additions & 161 deletions docs/contribute/documentation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,186 +6,56 @@ Contributing Documentation

**Last Updated:** January 2025

.. _contribute_docs_intro:

Introduction
============

The Tethys Platform documentation (https://docs.tethysplatform.org) is built using `Sphinx <https://www.sphinx-doc.org/en/master/>`_ and hosted on `Read the Docs <https://docs.readthedocs.io/en/stable/>`_. The documentation is written using a lightweight markup language called `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-primer>`_. Sphinx converts the reStructuredText files into HTML, PDF, and other formats.

This guide will help you get started with contributing to the Tethys Platform documentation. It covers essential topics and initial steps to get you up and running quickly.

.. _contribute_docs_files:

Source Files
============

The reStructuredText (RST) source files for the Tethys Platform documentation are located in the :file:`docs` directory of the `tethysplatform/tethys` repository. In this directory you will find the following files and directories:

* :file:`conf.py` - The Sphinx configuration file.
* :file:`index.rst` - The RST source file for the landing page of the documentation.
* :file:`Makefile` and :file:`make.bat` - Makefiles that are used in building the documentation.
* :file:`docs_environment.yml` - The conda environment file for building the documentation Python environment.
* :file:`README.md` - The README file for the documentation with reminders of the commands used to build the documentation.
* :file:`images` - A directory containing most, but not all, of the images used in the documentation.
* :file:`_static` - A directory containing static files such as images, CSS, and JavaScript.
* :file:`_templates` - A directory containing custom templates for the documentation.
* :file:`_build` - A directory containing the built documentation (only present after building the documentation).
* Over 200 RST files organized into many subdirectories.

Git Large File Storage
----------------------

The documentation includes many images and a few other binary files. To keep the repository size manageable, we use `Git Large File Storage (LFS) <https://git-lfs.github.com/>`_ to store these files. The images will not be downloaded automatically when you clone the repository. You will need to install Git LFS to download these files (see: :ref:`contribute_docs_build`).

Docstrings
----------

In addition to the RST files, many of the Python objects in the Tethys Platform codebase are documented with `Google Style Python Docstrings <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`_. These are incorporated into the documentation using a Sphinx extensions called `autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ and `napoleon <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html>`_. An example of a Google style docstring is shown below:

.. code-block:: Python
def some_function(arg1, arg2):
"""
This is a Google style docstring.
Args:
arg1 (int): The first argument.
arg2 (str): The second argument.
Returns:
bool: The return value. True for success, False otherwise.
"""
return True
.. _contribute_docs_build:

How to Build the Documentation
==============================

This section will guide you through the process of building the Tethys Platform documentation on your local machine.

1. **Install Prerequisites**

Before building the documentation, you will need to install the following prerequisites:

* `Miniconda <https://docs.anaconda.com/miniconda/install/>`_ - Python package manager
* `Git <https://git-scm.com/downloads>`_ - Version control system
* `Git LFS <https://git-lfs.github.com/>`_ - Git extension for managing image and binary files

2. **Clone the Repository**

Clone your fork of the Tethys Platform GitHub repository to your local machine (see: :ref:`contribute_development_process`):

.. code-block:: bash
git clone <FORK_URL>
3. **Initialize Git LFS and Pull Images**
Initialize Git LFS in the repository and pull the images:

.. code-block:: bash
git lfs install
git lfs pull
.. note::
The following guides will help you get started with contributing to the Tethys Platform documentation. Review the list of guides below and select the one that best fits your interests.

Once Git LFS is installed in your repository, you can commit new images to the repository in the normal fashion. Git LFS will automatically manage the storage of the images.
Getting Started
===============

4. **Create the Docs Environment**
Use this step-by-step guide to learn how to build the Sphinx documentation on your local machine. This is a great place to start if you are new to contributing to the Tethys Platform documentation.

Create the conda environment for building the documentation:
.. toctree::
:maxdepth: 1

.. code-block:: bash
documentation/building

conda env create -f docs/docs_environment.yml
Guidelines
==========

Then activate the environment:
Learn the best practices for contributing to the Tethys Platform documentation in the following guide. This guide outlines the standards that should be followed when writing documentation for the Tethys Platform to ensure consistency and quality.

.. code-block:: bash
.. toctree::
:maxdepth: 1

conda activate tethys-docs
documentation/guidelines

5. **Build the Documentation**

Build the documentation using the Makefile:

.. code-block:: bash
make html
The built documentation will be located in the :file:`docs/_build/html` directory.

6. **View the Documentation**

Open the built documentation in your web browser. Locate the :file:`index.html` file in the :file:`docs/_build/html` directory and open it in your preferred browser.


.. _contribute_docs_autobuild:

sphinx-autobuild
----------------

Any time you make changes to the documentation source files, you will need to rebuild the documentation to see the changes. To avoid having to manually rebuild the documentation every time you make a change, you can use the `sphinx-autobuild <https://github.com/sphinx-doc/sphinx-autobuild#readme>`_ tool. It watches the source files for changes and automatically rebuilds the documentation and reloads the browser when changes are detected.

To use `sphinx-autobuild`, run the following commands:

.. code-block:: bash
cd docs
sphinx-autobuild --host 127.0.0.1 --port 8001 . ./_build/html
.. _contribute_docs_clean:

Cleaning the Build Directory
----------------------------

Occasionally, you'll want to clean the build directory to rebuild the documentation from scratch. To do this, run the following command:

.. code-block:: bash
make clean
If the documentation doesn't open in your web browser automatically, navigate to http://127.0.0.1:8001 in your browser to view the documentation. The documentation will automatically rebuild and reload in the browser when changes are detected.

.. _contribute_docs_narrative:

Narrative Documentation
=======================

* Guides
* Tutorials
* Recipes

.. _contribute_docs_api:

API Documentation
=================

* Sphinx autodoc
* Writing Docstrings
* Referencing docstrings in RST files
* Mocking third party dependencies
Organization
============

.. _contribute_docs_demo_apps:
Take in this high-level explanation of Tethys Platform documentation source files and how they are organized. This guide will help you understand the structure of the documentation source files and how to navigate them.

Demonstration Apps
==================
.. toctree::
:maxdepth: 2

* Gizmo Showcase
* Layout Showcase
documentation/source

.. _contribute_docs_guidelines:
Demonstrations
==============

Screenshot Guidelines
=====================
Help maintain the demonstration applications and portals that are provided to help users get started with the Tethys Platform.

* Aspect Ratio
* Guest Mode in Browser
.. toctree::
:maxdepth: 2

.. _contribute_docs_i18n:
documentation/demo

Internationalization
====================

* i18n
* https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
Help translate the Tethys Platform documentation into multiple languages.

.. toctree::
:maxdepth: 1

documentation/i18n
93 changes: 93 additions & 0 deletions docs/contribute/documentation/building.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
.. _contribute_docs_build:

******************************
How to Build the Documentation
******************************

**Last Updated**: January 2025

This section will guide you through the process of building the Tethys Platform documentation on your local machine.

1. **Install Prerequisites**

Before building the documentation, you will need to install the following prerequisites:

* `Miniconda <https://docs.anaconda.com/miniconda/install/>`_ - Python package manager
* `Git <https://git-scm.com/downloads>`_ - Version control system
* `Git LFS <https://git-lfs.github.com/>`_ - Git extension for managing image and binary files

2. **Clone the Repository**

Clone your fork of the Tethys Platform GitHub repository to your local machine (see: :ref:`contribute_development_process`):

.. code-block:: bash
git clone <FORK_URL>
3. **Initialize Git LFS and Pull Images**
Initialize Git LFS in the repository and pull the images:

.. code-block:: bash
git lfs install
git lfs pull
.. note::

Once Git LFS is installed in your repository, you can commit new images to the repository in the normal fashion. Git LFS will automatically manage the storage of the images.

4. **Create the Docs Environment**

Create the conda environment for building the documentation:

.. code-block:: bash
conda env create -f docs/docs_environment.yml
Then activate the environment:

.. code-block:: bash
conda activate tethys-docs
5. **Build the Documentation**

Build the documentation using the Makefile:

.. code-block:: bash
make html
The built documentation will be located in the :file:`docs/_build/html` directory.

6. **View the Documentation**

Open the built documentation in your web browser. Locate the :file:`index.html` file in the :file:`docs/_build/html` directory and open it in your preferred browser.


.. _contribute_docs_autobuild:

sphinx-autobuild
================

Any time you make changes to the documentation source files, you will need to rebuild the documentation to see the changes. To avoid having to manually rebuild the documentation every time you make a change, you can use the `sphinx-autobuild <https://github.com/sphinx-doc/sphinx-autobuild#readme>`_ tool. It watches the source files for changes and automatically rebuilds the documentation and reloads the browser when changes are detected.

To use `sphinx-autobuild`, run the following commands:

.. code-block:: bash
cd docs
sphinx-autobuild --host 127.0.0.1 --port 8001 . ./_build/html
.. _contribute_docs_clean:

Cleaning the Build Directory
============================

Occasionally, you'll want to clean the build directory to rebuild the documentation from scratch. To do this, run the following command:

.. code-block:: bash
make clean
If the documentation doesn't open in your web browser automatically, navigate to http://127.0.0.1:8001 in your browser to view the documentation. The documentation will automatically rebuild and reload in the browser when changes are detected.
21 changes: 21 additions & 0 deletions docs/contribute/documentation/demo.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
.. _contribute_docs_demo:

**********
Live Demos
**********

**Last Updated:** January 2025

.. _contribute_docs_demo_apps:

Demonstration Apps
==================

* Gizmo Showcase
* Layout Showcase

Demonstration portals
=====================

* Official Demo Portal
* GEOGLOWS Portal
Loading

0 comments on commit 37ad9e1

Please sign in to comment.