Contributing

Documentation - Getting Started

Suitable For Level: Conductor Hat Propeller Beanie Engineer Hat

This page aims to provide the information required to help people contribute to our documentation.

If what is outlined in this page is too involved, and you simply wish to provide some content that we can add, clarify, or update, then simply get in touch with us via the Troubleshooting & Getting Help page and we can help you out.

Required Software

Refer to the Recommended Software page, in particular the section related to Python 3.x, GitHub Desktop and VSCode for the software necessary to contribute to the documentation.

GitHub Pages, Sphinx, and reStructuredText

Our website is hosted courtesy of GitHub Pages, is written in reStructuredText, with the HTML being generated by Sphinx.

reStructuredText is a markdown type language for typesetting documents from websites to PDF or LaTeX documents. Our Website is built upon this technology, so you should make yourself familiar with this by looking through the links provided.

There’s a handy reStructuredText QuickReference Guide here.

If you haven’t done so already, make sure you are familiar with how we use GitHub and are familiar with our Recommended Software.

GitHub repository and the sphinx branch

In order for GitHub pages to function correctly and automatically publish updated content, the content must be located in a specific repository named after the GitHub organisation, and therefore our website repository is dcc-ex.github.io.

In addition to this, rather than using the main or master branch, the default branch is called “sphinx”, so any branches created for contributing to documentation must use this as the parent, and all pull requests must be submitted against this same branch.

 


Procedure

Procedure overview

Ideally the documentation cycle would look like this..

Ideal GitHub Documentation Cycle

Changes to the original would be pulled down from the original repository directly to your local (PC) repository. You would push your changes to your GitHub website repository. Then create a Pull request to send them to the original for review.

While this is possible, both GitHub Desktop and VSCode make it extremely cumbersome to do so.

So instead a slightly longer approach is described below…

GitHub Documentation Cycle

Changes to the original would be pulled down from the original repository to your GitHub website repository with a Pull Request. You will then pull those changes to you local (PC) repository. You will push your changes to your GitHub website repository. Then create a Pull Request to send them to the original for review.

There are a number of possible ways to do this but the instructions below are reasonably simple and work:

After installing the required software (particularly GitHub Desktop and VSCode) …

One time only:

  1. Cloning the repository on the GitHub website

  2. Using GitHub Desktop to download the repository to your PC

Ongoing:

  1. Opening the repository in VSCode

  2. Making your changes

  3. Previewing your changes on your PC

  4. Using GitHub Desktop to push your changes back to your clone of the Repository on GitHub

  5. Creating a pull request to send your changes for review

You will periodically need to update your repository:

  1. Create a pull request on the GitHub website to get any changes from the original repository to your repository on GitHub website

  2. Use GitHub Desktop to pull the changes to your repository on your PC

One time only

1. Cloning the repository on GitHub website

  1. First you will need to create an account on Github if you don’t already have one.

  2. Go to the original repository https://github.com/DCC-EX/dcc-ex.github.io

  3. Click on the Fork button and create a new fork. (Do not alter the Repository name dcc-ex.github.io.)

You will now have a new fork located at https://github.com/<your_account_name>/dcc-ex.github.io. Take note of this for the next step.

2. Download the repository to your PC with GitHib Desktop

In GitHub Desktop:

  1. Select File ‣ Clone Repository

  2. Enter the name of you repository <your_account_name>/dcc-ex.github.io

  3. Select a location on your PC to store the repository.

  4. Click Clone

  5. Make sure that Sphinx is selected as the ‘Current Branch’

A copy of the repository should now be on the PC.

You can open it in VSCode by selecting Repository -> Open in Visual Studio Code

Ongoing

3. Open the repository in VSCode

You can open the repository in VSCode at any time by using File ‣ Open Folder and navigating to the folder you selected in step 2.

You can subsequently open the repository in VSCode using File ‣ Open Recent and selecting the repository name.

You can subsequently open the repository in VSCode from GitHub Desktop.

4. Make your changes

You can use the navigation tree on the left to find the file you want to change. Clicking on a file will open it in the edit window.

5. Live previews

Providing you followed the installation guide for VSCode on the Recommended Software page accurately, there are three methods available for generating previews as you are editing the reStructuredText code.

Esbonio Language server

This option uses the Esbonio Language server installed along with the reStructuredText extension. This option allows you to quickly preview a page you have been editing, as it continuously generates the preview in the background.

To view the preview you can

  • click on the preview button on the top right, or

  • Press <Ctrl>` + <Shift> + r and it will open the live preview in a new tab in VSCode. In addition to this method, you can also press <Ctrl>` + k followed immediately by <Ctrl>` + r.

This will generate the live preview in a split pane within VSCode. Every time you save the page you are working on, the live preview will automatically update.

The downside to using this method is that previews are only generated for pages you are actively editing, rather than the entire website. Therefore, prior to submitting any pull requests, it is essential that you follow the build process either as outlined below to emulate the GitHub Pages deployment, or in following section.

This will ensure the entire website is still able to be built successfully after any updates.

Emulate GitHub Pages deployment

The recommended method for local previews of the website documentation is to emulate the GitHub Pages deployment process, as this will not only generate a preview of the content, but will also ensure the same versions of the various Python packages are used to generate the preview, which will highlight any functionality issues arising out of new or different versions.

Right now this can only be done on Windows until a suitable bash script is created for Linux.

  1. Open a command prompt.

  2. Change to the directory where the “dcc-ex.github.io” repository has been cloned.

  3. Run the command “local_deploy.bat”.

  4. You will need to scroll up to review the output and ensure no errors are reported.

  5. The list of installed package versions is also output which is of help if issues are observed when previewing.

  6. If any errors have been generated, these must be resolved prior to submitting a pull request.

Once the build of the website completes successfully, preview it locally by opening the main “index.html” file locally in a web browser.

This file can be found in the “docs\_build\html” folder within the “dcc-ex.github.io” folder.

Local Sphinx build

To refresh the entire website while editing, it is necessary to run the equivalent commands that the GitHub publishing workflow runs to ensure no issues have been introduced.

To build the website using Sphinx, follow these steps:

  1. Open a command prompt.

  2. Change to the directory where the “dcc-ex.github.io” repository has been cloned.

  3. Run the command “make clean”, review the output and ensure no errors are reported.

  4. Run the command “make github”, and likewise review the output for errors.

  5. If any errors have been generated, these must be resolved prior to submitting a pull request.

Once the build of the website completes successfully, preview it locally by opening the main “index.html” file locally in a web browser.

This file can be found in the “docs\_build\html” folder within the “dcc-ex.github.io” folder.

6. Push your changes to your GitHub repository

You will need to

  • Commit your changes

  • Push your changes

In GitHub Desktop:

  • Open/select the repository

  • note and review the changes that have been made

  • Add a Summary of your changes

  • Add a Description of your changes, if the summary is not sufficient

  • click Commit to Sphinx

  • click Push origin

7. Creating a pull request to send your changes for review

  1. Open the GitHub website

  2. Open/select your repository https://github.com/<your_account_name>/dcc-ex.github.io

On the ‘code’ page you should see “This branch is x commit(s) ahead of DCC-EX/dcc-ex.github.io:sphinx.”

3. Click on the x commit(s) ahead of hyperlink 5. Confirm or add to the title and documentation fields 6. Click on the Create pull request button

This creates a pull request to be reviewed by the documentation team

Periodic

To see the changes that other people have made to the original repository you need to periodically refresh your repository on both GitHub website and locally

a. Get any changes to your repository on GitHub website

  1. Open the GitHub website

  2. open/select your repository https://github.com/<your_account_name>/dcc-ex.github.io

On the ‘code’ page you should see “This branch is x commit(s) behind DCC-EX/dcc-ex.github.io:sphinx.”

If does not say you are ‘behind’ there is nothing to do. Stop here.

If you are behind…

3. Click on the x commit(s) behind hyperlink 5. Add to the title and/or documentation fields. This does not matter so entering just Catchup is fine. 6. Click on the Create pull request button 7. Click on the Merge pull request button 7. Click on the Confirm merge button

Any changes are now also in your repository on the GitHub website.

b. Pull the changes to your repository on your PC

In GitHub Desktop:

  1. Click on the Fetch origin button`

Any changes are now also in your repository on PC.


Additional

Your own github pages

You can optionally, setup github pages from you own repository on the GitHub website. This allows you make changes that other people can view before creating a pull request.

  1. Open the GitHub website

  2. Open/select your repository https://github.com/<your_account_name>/dcc-ex.github.io

  3. Click the branches link

  4. On ‘Branches’ page click new Branch

  5. Give the new branch the name gh-pages

  6. Select a Source of DCC-EX/dcc-ex.github.io and gh-pages

  7. clich Create New branch

  8. Open the Settings page

  9. Select Pages in the left navigation

  10. Choose Deploy from a branch

  11. Choose gh-pages and root

  12. Click Save

In theory that should be enough, but the last time we tried this we also needed to create a manual build action. If you go to the ‘Actions’ page and you can’t see an action named ‘Docs’, then contact the development team nd we will halp you create a manual build action. (Which for some unknown reason then shows the automatic ‘Docs’ action.)

Building the pages and deplying takes time, every time you push any changes, but you will eventually be able to see your own version of the website at https://<your_account_name>.github.io/dcc-ex.github.io/.

You can see the state of the processing of your changes by looking at the Actions page. It will also tell you there if there are any errors.