diff --git a/docs/contrib.rst b/docs/contrib.rst index e74ecc3c..da259b50 100644 --- a/docs/contrib.rst +++ b/docs/contrib.rst @@ -322,6 +322,36 @@ add it to either the ``docs/internal_api/index.rst`` or ``docs/user_api/index.rst`` file, depending on whether the function is intended for internal or external use. +Editing other documentation files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We welcome changes and improvements to all parts of our documentation (including +this guide)! You can find these files in the ``docs`` directory. + +These files are mainly written in `reStructuredText +`__, +but additional file types such as ``.md`` and ``.ipynb`` are also used. + +Important documentation files to know about include: + +* ``docs/index.rst``: This file is the main page of the documentation. Files + added to ``toctree`` blocks in this file will be included in the documentation + as top-level subpages. + +* ``docs/contrib.rst``: This file is the source for this guide! + +* ``docs/conf.py``: This file contains the configuration for building the documentation. + +* ``docs/examples/*.ipynb``, ``docs/examples.rst``, and ``docs/gallery.yml``: + These files are used to generate the jupyter notebook examples in the + documentation. Notebooks in the ``docs/examples/`` directory are added to the + documentation by adding them to the ``toctree`` in ``docs/examples.rst`` and + linked to their cover picture by addidng them to the ``docs/gallery.yml`` + file. + +See the `sphinx documentation `__ for +more informatiion about writing sphinx documentation. + Generate the documentation locally ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -348,21 +378,68 @@ from your PR and see any warnings or errors on your build. Contribute your code -------------------- -Once you have prepared your changes and are ready for them to be reviewed by the GeoCAT team, you can open a pull request. This section describes how to open a pull request and what to expect after you open it. +Once you have prepared your changes and are ready for them to be reviewed by the +GeoCAT team, you can open a pull request. This section describes how to open a +pull request and what to expect after you open it. +Push your changes to your fork +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once you have made your changes locally, you will need to push them to your +branch on your fork on GitHub. To do this, use the following command: + +.. code-block:: bash + git push +From here, you can request that your changes be merged into the main repository in the form of a pull request. +Making a pull request +^^^^^^^^^^^^^^^^^^^^^ + +GitHub has extensive `pull request guides and documentation +`__ that we recommend. This section +describes the basics for our workflow. + +From your branch on your fork, open the "Pull requests" tab and click the "New +pull request" button. Make sure the "base repository" is "NCAR/geocat-comp" and +the "base" branch is set to "main", wiht the "head repository" and "compare" +branch set to your fork and prepared branch, respectively. + +From this page, you can see a view of the changes you have made in your branch. + +We recommend adding a short, descriptive title to your pull request. The body of +the pull request should autofill with our pull request template, which has it's +own set of directions. Please fill out the relevant sections of the template, +including adding a more detailed description of your changes. + +Once you have filled out the template, click the "Create pull request" button. +This will open your pull request on the ``geocat-comp`` repository. + +If you want to open a pull request but are not ready for it to be reviewed, you +can open the pull request as a draft. This is also a good way to get feedback on +your work that might not be ready to contribute yet. + +Addressing feedback +^^^^^^^^^^^^^^^^^^^ + +After you open your pull request, the GeoCAT team will review it and +may provide feedbac like asking for changes or suggesting improvements. You can +address this feedback by making changes to your branch and pushing them to your +fork. The pull request will automatically update with your changes. + +The GeoCAT team appreciates your contributions and the interactive process of +reviewing pull requests, and will do our best to review your pull request in a +timely manner. It is totally normal to have to make several rounds of changes to +your pull request before it is ready to be merged, especially if you are new to +the project. -Contibuting to documentation ----------------------------- +Once your pull request is approved by a core maintainer and passes the relevant +checks, it will be merged into the main repository! -- where -- sphinx -- rst -- how to build +Delete your branch +^^^^^^^^^^^^^^^^^^ -Opening a pull request ----------------------- -- pull request template +We recommend deleting your branch after your pull request is merged. This will +help keep your fork clean and organized, but is not required.