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