Documenting Instructions

Installation

Install Conda

You can install Anaconda or Miniconda to install conda package manager (if you don't know the difference you should install anaconda).

Create documentation environment

Now we need to create the appropriate environment for documenting by installing all the necessary tools. To do so we have provided you an environment droplet, which is a recipe for a series of installations that create the aforementioned environment. For that, after directing to the root folder of this project where the environment droplet (environment.yml) is located, you need to run the following command:

conda env create -f environment.yml

Start Work on Documentation

After finishing your work on documentation you need to shutdown the server and deactivate the environment.

Activate the Environment

Now that you have created the appropriate environment, you need to activate the environment to be able to work inside it. For that, as you are in the root folder of this project, you need to run the following command:

conda activate spatial_computing_docs

If the command line is now indicating the name of the environment in parenthesis, it means that the environment is activated. Similar to this

(spatial_computing_docs) {your username}@{your computer name} spatial_computing_project_template %

Run the Local Server

Now that the environment is activated, we need to run the local server to be able to see the result of changes in the local version of the documentation website. For that, run the following command:

mkdocs serve

After running this command, if the server has started to work successfully, you should see the following line in the command line:

INFO    -  Serving on http://127.0.0.1:8000

This means that the server is accessible at http://127.0.0.1:8000. If you open your browser and go this link you should see a local version of the site.

Writing Your Documentation

In the documenting process you need to head to the docs folder and edit the .md (markdown) files, since the website is build from these files.

In the root of this project, you can edit the configurations of your project in mkdocs.yml file:

Adding o removing pages
Add markdown extensions. Some of the useful extensions:
- arithmatex for writing mathematics
- highlight for code highlighting
Customizing the looks of your documentation
Adding MkDocs Plugins, such as:
- mknotebooks for including python notebooks in the documentations

Finish Work on Documentation

Server Shut Down

To shutdown the server, you need to press Ctrl+C in the command line. The following should appear in the command line:

INFO    -  Shutting down...

Deactivate Environment

After shutting down your server the command line is back to the normal state and you can run commands again. To deactivate your environment you need to run the following command:

conda deactivate

Deployment of the Documentation Site

Build and Deploy

to deploy your documentation website, you need to run the following command in the root of this repository:

mkdocs gh-deploy

This command will create a new branch in your repository called gh-pages and build your site in it. It will then push the new branch to your remote repository automatically. It will also create a site folder in your root directory containing all of your site files. Since this folder is added .gitignore file, it won't be committed or pushed to the remote repository.

Setup GitHub Pages

For the first time, you need to configure the GitHub Pages service on your GitHub repository so it wil automatically build your documentation website whenever you deploy your site. To do this:

Go to your repository setting,
got GitHub Pages section,
select gh-pages branch,
select /(root) location,
click on the save button.

The setting page will refresh, and now if you go to the address that is provided at the GitHub Pages section, Wola, here is your documentation!