Getting started

This chapter covers three topics:

How to set up and use the WISE environment.
How to build and view the documentation locally, using Sphinx.
How to publish the documentation online using GitHub Pages and GitHub Actions.

It also works as a quick reference in case you don’t remember a step in the process.

Warning

If you are an end user (a.k.a. a “thematic”) this is not the page you’re looking for :-)

This documentation is intended for developers and contributors who are responsible for creating and maintaining the documentation for WISE dataflows and projects.

Setting up the environment 

Make sure you have Anaconda available on your system.

This project uses Conda to manage its dependencies and ensure a reproducible workflow.

All required packages for data analysis and documentation are specified in the environment.yml file that you can download here.
Open the Anaconda PowerShell (Windows) or your terminal of choice (Linux/Mac).

Navigate to the root directory of the project where the environment.yml file was copied to:
```
cd path/to/your/project
```
Run the following command to build the environment. This will download and install all the exact package versions required for the project:
```
conda env create -f environment.yml
```
This process may take a few minutes, depending on your internet connection and the number of packages being installed. Conda will handle all dependencies and ensure that the environment is set up correctly.

Once the installation finishes, you need to activate the environment before running any scripts:
```
conda activate wiseEnvironment
```
You should now see (wiseEnvironment) at the beginning of your terminal prompt.

Updating the environment 

If the project’s dependencies change and the environment.yml file is updated, you can refresh your local setup without recreating it from scratch by running:
```
conda env update -f environment.yml --prune
```

Writing documentation 

We use Sphinx for documentation: it allows us to write in reStructuredText (reST) format, which is a simple and powerful markup language. You can also write in Markdown format using MyST parser, which is compatible with Sphinx.

Files with the .rst extension are processed as reST, while files with the .md extension are processed as Markdown. You can choose the format that best suits your needs and preferences.

If you are a developer working on WISE documentation, you can use sphinx-autodoc2 for automatic docstring generation.
All you need is Notepad++ or any text editor of your choice to create and edit the documentation files.
You can also use Visual Studio Code for a more feature-rich experience.
You you already have documentation in other formats, you may convert it using Pandoc.

Pandoc 

Pandoc is a free and open-source document converter, available for Windows, Linux and Mac.

It can convert files in formats such as HTML, PDF, DOCX, ODT, etc. to and from reStructuredText and Markdown (including the CommonMark flavour supported by Sphinx and GitHub).

You can use it to convert existing documents to *.rst or *.md format, before editing them with a text or code editor (e.g. Notepad++, Visual Studio Code).

pandoc --from=docx --to=rst --output=myfile.rst --extract-media=img myfile.docx

Refer to https://pandoc.org/MANUAL.html for a full list of options (besides the ones listed below).

--from=FORMAT

Input format.
- commonmark (CommonMark Markdown)
- docx (Word docx)
- rst (reStructuredText)
--to=FORMAT

Output format
- commonmark (CommonMark Markdown)
- docx (Word docx)
- rst (reStructuredText)
- pdf (PDF)
--output=FILE

Write output to FILE.
--defaults=FILE

Specify a set of default option settings. FILE is a YAML or JSON file whose fields correspond to command-line option settings. All options for document conversion, including input and output files, can be set using a defaults file.
--fail-if-warnings[=true|false]

Exit with error status if there are any warnings.
--shift-heading-level-by=NUMBER

Shift heading levels by a positive or negative integer. For example, with –shift-heading-level-by=-1, level 2 headings become level 1 headings, and level 3 headings become level 2 headings. Headings cannot have a level less than 1, so a heading that would be shifted below level 1 becomes a regular paragraph.
--extract-media=DIR|FILE.zip

Extract images and other media contained in or linked from the source document to the path DIR, creating it if necessary, and adjust the images references in the document so they point to the extracted files.
--template=FILE|URL

Use the specified file as a custom template for the generated document. Implies –standalone.
--table-of-contents[=true|false]

Include an automatically generated table of contents (or, in the case of latex, docx, and rst, an instruction to create one) in the output document.
--toc-depth=NUMBER

Specify the number of section levels to include in the table of contents. The default is 3 (which means that level-1, 2, and 3 headings will be listed in the contents).
--list-of-figures[=true|false]

Include an automatically generated list of figures (or, in some formats, an instruction to create one) in the output document. This option only has an effect on latex, and docx output.
--list-of-tables[=true|false]

Include an automatically generated list of tables (or, in some formats, an instruction to create one) in the output document. This option only has an effect on latex, and docx output.
--reference-links[=true|false]

Use reference-style links, rather than inline links, in writing Markdown or reStructuredText. By default inline links are used. The placement of link references is affected by the –reference-location option.
--reference-location=block|section|document

Specify whether footnotes (and references, if reference-links is set) are placed at the end of the current (top-level) block, the current section, or the document. The default is document.
--figure-caption-position=above|below

Specify whether figure captions go above or below figures (default is below). This option only affects HTML, LaTeX, Docx and ODT output.
--table-caption-position=above|below

Specify whether figure captions go above or below figures (default is above). This option only affects HTML, LaTeX, Docx and ODT output.
--markdown-headings=setext|atx

Specify whether to use ATX-style (#-prefixed) or Setext-style (underlined) headings for level 1 and 2 headings in Markdown output. (The default is atx.) ATX-style headings are always used for levels 3+.
--list-tables[=true|false]

Render tables as list tables in RST output.

Notepad++

Notepad++ is a free source code editor and Notepad replacement that supports several programming languages. It is only available for Windows.

reStructuredText and Markdown are not among the languages natively recognised by Notepad++, but can be added using the Notepad++ User Defined Languages Collection.

Follow the link to download the Notepad++ ReST syntax file.
Follow the link to download the Notepad++ Markdown syntax file.

Visual Studio Code 

Visual Studio Code is a open source code editor for Windows, Linux and Mac. It has a large number of extensions available, including some for reStructuredText.

If you are using Visual Studio Code, you select the wiseEnvironment Conda environment as your Python interpreter to ensure that all Sphinx extensions and dependencies are available while editing and previewing your documentation.

In Visual Studio Code, open the Command Palette (Ctrl+Shift+P) and type “Python: Select Interpreter”.
Choose the interpreter that corresponds to your wiseEnvironment Conda environment.

This document opened in Visual Studio Code.

Sphinx 

Sphinx is a Python documentation generator.

If your using the wiseEnvironment Conda environment, Sphinx should already be installed. The wiseEnvironment includes the sphinx-autobuild package, which allows you to automatically rebuild and preview your documentation in a web browser as you edit it (see next section).

Building documentation 

Before building the documentation, ensure your Conda environment is activated:

conda activate wiseEnvironment

“Live build” (Recommended for Development)

If you are actively writing or editing documentation, the best way to preview your changes is using sphinx-autobuild. This will start a local web server and automatically refresh your browser whenever you save a file.

Start the autobuild server.

Navigate to the root of your project and run:
```
sphinx-autobuild docs docs/_build/html
```
(Note: If your Sphinx source files are in a different directory than `**docs**`, adjust the paths accordingly).
View the docs:

Open your web browser and navigate to the local URL provided in the terminal (usually http://127.0.0.1:8000).

Standard HTML Build 

If you just want to generate the static HTML files once without starting a persistent server, you can use the standard build command.

Build the HTML files:

Navigate to your documentation directory (usually docs/) and run:
```
make html
```
(On Windows, use `.make.bat html` instead).
View the docs

Open the generated index.html file in your browser. You can typically find it at:
```
docs/_build/html/index.html
```

Publishing to GitHub Pages 

Once your documentation is ready to be shared, you can automatically publish it using GitHub Pages. The best way to do this is by setting up a GitHub Actions workflow that automatically builds and deploys your HTML files whenever you push changes to your main branch.

Create a GitHub Actions workflow

Create a new configuration file in your repository at .github/workflows/documentation.yml. Use the configuration in the documentation.yml file that you can download here.
Configure your repository settings

Once the action runs for the first time, it will create a new branch called gh-pages.
- Go to your repository on GitHub.
- Navigate to Settings > Pages.
- Under Build and deployment, set the Source to “Deploy from a branch”.
- Select the gh-pages branch and the / (root) folder, then click Save.

Your documentation will now be publicly accessible at https://<your-username>.github.io/<your-repository-name>/.

Warning

Before publishing your documentation, make sure to review it locally and ensure that it is accurate and up-to-date. Once published, the documentation will be publicly accessible, so it’s important to verify its quality beforehand.

Make sure that your WISE project manager is aware of the publication and has approved the content, specially is it is being published in an organisational repository.

Links