Editing the Documentation
=========================

The source code is currently hosted on `Dr. McCurry's Personal Forgejo Server <https://ivory-coati.pikapod.net/>`_. You will need an account, so please check
your email for your password if you haven't already set up and changed your
password. The source code is tracked using ``git``, a type of *version control
system*, that notes every change ever made to a file. It attributes changes to
specific users (or emails) so that you always know where a change came from and
when it was introduced. The true power here is that changes can easily be merged
or removed if needed without causing odd conflicts as multiple people edit a
document individually. If you're interested, you can read more on ``git``
`online <https://git-scm.com/>`_, but it is not necessary for CHEM442.

.. note::

   You do not need to install any additional software to edit the documentation,
   but you are welcome to try it out if interested!

A popular host for git repositories is `GitHub <https://github.com/>`_, but it
is owned by Microsoft and has recently forced a lot of AI on users, so Dr.
McCurry has chosen to host his own using `Forgejo <https://forgejo.org/>`_.
Forgejo shares a lot of similarities with GitHub, so if you ever do work on
GitHub (or alternative sites like `Codeberg <https://codeberg.org/>`_), you'll
feel right at home.

Anyway, let's cover how to edit the documentation. There will be some new terms
that we'll come across, but you probably don't need to know the intricate
details of ``git`` unless you are interested!

Forking the documentation repository
------------------------------------

.. tip::

   This will work best on a full computer, rather than a phone. These directions
   have been written assuming that you're at a keyboard.

1. After logging in to Forgejo, you will be presented with a list of recent
   changes to some repositories (or projects) that you follow. Dr. McCurry has
   added the CHEM442 class to the CHEM442 team, so you should already be
   following the **CHEM442/InstrumentDocs** and **CHEM442/442LabManual**
   repositories. For the instrument documentation, we want
   **CHEM442/InstrumentDocs**, so click on that repository under the
   Repositories tab on the right side of your screen.

2. You will be presented with the "source code" of the documentation. The
   documentation is built from a series of files that are all written in plain
   text. These have simple formatting and it should be easy to pick up. Don't
   worry — you don't actually need to code anything! The content you're seeing is
   owned by Dr. McCurry, so you won't actually be able to edit it directly.
   Instead we're going to "fork" (create a copy) of this code to your own
   repository. Click the "Fork" button at the top right of the screen.

3. You will be presented with a "New repository fork" screen. The default
   options should be OK to use, so just click the "Fork repository" button at
   the bottom of the screen.

4. You will be brought to **your** repository. Note that the top of the page now
   says *username*/InstrumentDocs instead of CHEM442/InstrumentDocs.

Editing a file and committing changes
-------------------------------------

All edits will be made in *your* forked repository, rather than the
CHEM442/InstrumentDocs repository. Whenever you log in to Forgejo in the future,
head to your version for edits!

.. important::

   Sometimes Dr. McCurry's source code will get ahead of yours due to inclusion
   of edits from other students. If you ever see a message at the top of your
   repostiory that says something like

     This branch is 1 commit behind CHEM442/InstrumentDocs:main

   hit the "Sync" button to bring in the changes **before** you do your edits!

I'm assuming we'll edit an instrument, so let's take a look at one!

1. Click the ``instruments`` folder in your repository.

2. You will be presented with a list of instruments that we have on campus.
   Click the folder for the instrument you would like to work on.

3. All instruments have a ``index.rst`` file. This is the general overview of
   the instrument. If you would like to edit the procedure, I would encourage
   you to make edits in a ``procedure.rst`` file if it exists. I'm hoping the
   file names are explanatory enough. When in doubt, use ``index.rst`` and I'll
   move it around as needed. Click on the file you would like to edit.

4. Here, you'll see the raw file! Near the top of the file, there should be a
   pencil icon that you can click to start editing.

5. The file is written using the ReStructured Text format. There is a fantastic
   `primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
   online that lists a lot of the possibly useful formatting features. Feel free
   to use any, but generally, you will just type if you need paragraphs, or put
   a ``1.`` or ``2.`` in front if you want a numbered list. The numbers don't
   actually need to be in order, the document generator will fix that! Note that
   headings are just lines of text that are "underlined" with either hyphens
   (-), equal signs (=), or some other character. Switching between different
   characters moves from heading to subheading to subsubheading, etc. Type in
   your edits to the file.

6. Once done, scroll to the bottom of the page. Here's where you'll save (or
   commit) your changes. Generally, it's a good idea to be descriptive about
   what you did, but when in doubt, you can use the default (e.g., "Update
   *instrument/index.rst*"). Keep the "Commit directly to the ``main`` branch
   checked" and hit "Commit changes" when you're done.

Note that these changes have only been made to *your* repository. In order to
merge them to the class we need to start a ":ref:`Pull request <pullrequest>`"!

New files and images
^^^^^^^^^^^^^^^^^^^^

.. note::

   I will not require you to upload or insert images, but I do encourage you to
   take screenshots as this helps future users follow steps a bit more clearly.

If you would like to include images that you have taken, please send me an email
with the desired images named with placeholders that you include in your
documentation edits. For example, send me a file named ``scan1.png`` and inside
your documentation, include the phrase ``scan1.png goes here``.

While it would be great if you could upload your images directly to Forgejo, I
have to pay for storage and would appreciate the ability to edit or scale down
your images into a more manageable size!

For new text files, feel free to use the "Add file" button at the top of your
repository and commit changes as described above.

.. _pullrequest:

Creating a pull request
-----------------------

You can create multiple commits (changes) prior to creating a pull request. Make
sure not to hold off on creating a pull request too long, though, or your edits
won't match the new documentation!

1. Click the "Pull requests" tab near the top of your repository (under your
   repository name).

2. Click "New pull request".

3. Notice the direction of the arrow that's shown. We want to pull *your*
   changes into *Dr. McCurry's* repository. Change the left dropdown to
   ``CHEM442:main``. The right dropdown should stay at "pull
   from:*username*:main".

4. Review the changes. You should note a "-" next to lines that have been
   removed and a "+" next to lines that have been added. Click the "New pull
   request" button if the changes look good.

5. A default commit message should be provided for you. You can add in any other
   comments or details that you want me (and the class) to see. Once finished,
   click "Create pull request".

6. Now, you just wait for me to review your request and hopefully I'll pull it
   in to the official documentation!