Getting Started

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 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.

Cloning the repository 

For this section, we are assuming that you are using VSCode with Git installed, allowing the built-in functionality for Git management in VSCode to work.

To clone the documentation repository, and ensure you are on the correct branch, follow these steps:

In VSCode, either click on the Source Control icon in the left pane, or press <Ctrl> + <Shift> + “g” + “g” (Yes, press “g” twice).
Click the “Clone Repository” button.
Enter the documentation repository URL “https://github.com/DCC-EX/dcc-ex.github.io” then press <Enter>.
Select the appropriate folder on your hard drive to clone it to, then click “Select Repository Location”.
The clone will take a minute or two to complete depending on the speed of your computer and internet connection.
Once complete, click “Open”.
At the bottom of the window, ensure that the branch “sphinx” is listed beside the Source Control icon.
When you’re ready to start editing, click the Source Control or press <Ctrl> + <Shift> +”g” + “g” again.
Click the three dots “…” beside “SOURCE CONTROL” in bold text and select “Checkout to”.
Enter a new name for your branch, then click “Create new branch”.

At this point, any editing you do will be on a new branch linked to the parent “sphinx” branch.

While editing, be sure to save often, stage and commit your changes, and publish them. This way, should anything go wrong with your computer, your work will be saved in GitHub rather than be lost.

Live previews 

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

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.

Open a command prompt.
Change to the directory where the “dcc-ex.github.io” repository has been cloned.
Run the command “local_deploy.bat”.
You will need to scroll up to review the output and ensure no errors are reported.
The list of installed package versions is also output which is of help if issues are observed when previewing.
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.

Esbonio Language server 

The next 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, 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” which 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 above 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.

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:

Open a command prompt.
Change to the directory where the “dcc-ex.github.io” repository has been cloned.
Run the command “make clean”, review the output and ensure no errors are reported.
Run the command “make github”, and likewise review the output for errors.
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.

Submission Procedure 

Once you are finished editing and are ready to have your updates published you will need to submit a pull request for one of the team members to approve and review.