How to suggest structural changes¶

When making large changes to a Sphinx document or set of documents, it is easiest if you have locally installed Sphinx to your machine. This allows you to locally build the website to check that your changes work as intended.

Necessary installations for local builds¶

Install Git¶

To clone the website your repository, you will need Git installed on your machine. This allows you to interact with the GitHub repository and commit your changes to version control. You can accept the defaults for the installation options.

Please follow our instructions for installing Git.

Install Miniconda¶

You will need to install a Python distribution in order to run Sphinx. We recommend to installing Anaconda or Miniconda. Anaconda contains hundreds of pre-installed packages, none of which we need for this project however. Miniconda, on the other hand, simply includes the tools we need to install a virtual Python environment to use for this project using conda.

If you already have a Python distribution installed and would like to use it, you can skip this installation.

Installation adapted from the Anaconda documentation.

Windows

Open Git Bash.

Download the installer by running this command in Git Bash:

curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe -o miniconda.exe

Run the installer:
```
./miniconda.exe
```
This will open a graphical interface to install. Follow the instructions and accept the defaults until you reach Advanced Installation Options. If you use another Python installation and would like to keep using it primarily, uncheck “Register Miniconda3 as my default Python 3.xx”. Otherwise, you can leave it checked.
Click “Install” and then “Next” and “Finished” once completed.
Remove the installer:
```
rm miniconda.exe
```
To make sure you have access to conda when booting Git Bash, run the following:
```
echo '. ~/miniconda3/etc/profile.d/conda.sh' >> ~/.bashrc
```
Restart Git Bash.

MacOS

Open Terminal.
Make a directory to store miniconda in with this command in Terminal:
```
mkdir -p ~/miniconda3
```

Download the installer:

curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ~/miniconda3/miniconda.sh

Run the installer:

bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3

Remove the installer file:
```
rm -rf ~/miniconda3/miniconda.sh
```

Initialize conda in bash and zsh:

~/miniconda3/bin/conda init bash
~/miniconda3/bin/conda init zsh

Linux

Open Terminal.
Make a directory to store miniconda in with this command in Terminal:
```
mkdir -p ~/miniconda3
```

Download the installer:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh

Run the installer:

bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3

Remove the installer file:
```
rm -rf ~/miniconda3/miniconda.sh
```

Initialize conda in bash and zsh:

~/miniconda3/bin/conda init bash
~/miniconda3/bin/conda init zsh

To use conda, you can use conda activate:

conda activate

This will slightly change your console view to add (base), which is the default conda environment. To make conda activate when you open your console, you can run:

echo 'conda activate' >> ~/.bashrc

When you reboot, the change will be in effect.

Install make¶

make is a tool that automates the building of files. We will use it to build the website from the source files.

To see if make is already installed, you can run:

make --version

To install make, you can use the package manager for your operating system.

Windows

Windows has a more involved installation process. We recommend using scoop to install make. If you do not have scoop installed, you can install it by following the instructions at https://scoop.sh/. Open PowerShell, and run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

Give the process the permissions it needs, and accept any prompts that appear.

Then, you can install make with this command:

scoop install make

Restart Git Bash and run make --version again to confirm the installation was successful.

MacOS

If you do not have Homebrew installed, you can install it by following the instructions at https://brew.sh/.

Then, you can install make with this command:

brew install make

Linux

On Ubuntu or Debian:

sudo apt-get install make

On CentOS or Fedora:

sudo dnf install make

Install a text editor¶

To edit the document files, you will need a text editor. We recommend VS Code, as it is a flexible editing environment. Once you install VS Code, make sure to also install the Python extension.

Clone the repository¶

If you have not already, make sure to fork the repository to your personal GitHub account. Once you’ve made the fork, you can clone your forked repo and use a text editor (like VS Code). You can use the code below, replacing <your-username> with your GitHub username:

git clone https://github.com/<your-username>/deisdata.github.io.git

Install sphinx and dependencies¶

We’re going to use conda to create a virtual environment. This allows us to download and install different software with compatible versions to installed without conflicts arising. We will use a yml file to specify the packages we want to install.

Navigate to the root directory of the repository in your console. This is the directory that contains the environment.yml file. Then run:

conda env create -f environment.yml

This will create a new conda environment with all the packages specified in the environment.yml file. You may be prompted to accept ToS for some software, so please read and accept.

To activate the environment, run:

conda activate sphinx

You should see the name of the environment, (sphinx), appear in your console prompt. If you ever need to update the environment with new packages, you can run:

conda env update -f environment.yml

This will update the environment to include any new packages specified in the environment.yml file.

Making changes¶

Adding a new set of pages¶

While you can in theory place a new document RST file anywhere in the source/ directory, our structure is to put the home page of a topic directly in the source/ directory. The subpages for that topic are stored in subdirectories of source/. For example, the Python documents are stored in source/python/. Please follow this convention when adding any new pages.

Make sure to update the toctree of relevant documents to include any documents you add. When you build the website, you’ll get a warning if there is a document that’s not included in any toctree.

Make sure to stage and commit all changes you make in the repository.

`make html`¶

Once you’ve edited documents, you will want to deploy the website on your local machine to ensure all the changes you’ve made are working as intended. Anyone reviewing the changes should also do this before deploying the changes to the live website.

To do this, we’ll be using the make html command. This command will build the website and render the .rst documents into html files.

Make sure you navigate to the docs/ directory and run conda activate sphinx before running make html.

The make html command sometimes runs into issues when run repeatedly without making changes to any documents, even if you change other files. If this occurs, make a small change to a document (like adding space or blank line) and then rerun make html.

Once make html runs successfully, go to your file browser and find the folder for the website. The html files you’ve just built will be in docs/build/html/. You can open these files in any browser by double clicking them, and from here, you can navigate the site just like you would on the live website.

Once you are ready, you can commit your changes and push them to your forked repo. Due to the default .gitignore settings, the build will not be commited; only the source files will be in version control.