SimCenterDocumentation

This is the repository where documentation for SimCenter software is maintained. The current documentation is in reStructuredText format and is built using the Sphinx Python module.

Contributors should follow the style reference for guidelines on documentation formatting.

Build instructions are outlined below, with further details provided here.

Directory Structure

docs/ - the folder containing the most up to date material (all other directories contain legacy material)
docs/Makefile - Legacy Linux and MacOS makefile for building current document
docs/make.bat - Legacy Windows make.bat to do same thing
docs/conf.py - configuration file (in this file set app for which doc is requiretd)
docs/index.rst - main index file, which pulls in files in docs/common
otherFolder - ignore as these contain legacy text files

Building the Documentation

Documentation files for a particular SimCenter application can be built by completing the following steps.

1. Download this repository from Github

For Git users, this can be done by running the following command in a terminal.

git clone https://github.com/NHERI-SimCenter/SimCenterDocumentation.git

Most of the remaining terminal commands should be run from the root of this repository, herein referred to as the documentation root (i.e., the top-level of the folder that was created after running the previous command).

2. Install dependencies

Install the project dependencies by running the following terminal command from the documentation root:

pip install -r requirements.txt

pip3 install -r requirements.txt

Note: A Python 3 installation must be available in your terminal environment. The pip command is used on Windows and pip3 on a Mac. If you do not have admin rights, add a -U before the -r.

3a Build with Make

On systems with make installed, the following command can be run from the documentation root to build a particular documentation target. make is typically available by default for MacOS and Linux users and can readily be installed on Windows. However, Windows users who do not wish to install make may alternatively use the Powershell script outlined in step 3b.

make <app> <target>...

where <app> is one of:

`<app>`	`<app-name>`
`pelicun`	Pelicun
`qfem`	quoFEM
`r2d`	R2D
`pbe`	PBE
`we`	WE-UQ
`ee`	EE-UQ
`hydro`	HydroUQ
`rtm`	Requirements matrix

and <target> is one of:

`<target>`	description
`web`	Generate HTML output in the app publishing repository (i.e., `../<app-name>-Documentation/`).
`html`	Generate HTML output in `build/<app-name>/html/`.
`latex`	Generate LaTeX output in `build/<app-name>/pdf/`.
`pdf`	Generate PDF output in `build/<app-name>/pdf/`.

Several targets may be chained at the end of a command for a particular application, as shown in the examples below.

3b Build HTML from Powershell

The legacy Powershell script can be run from the docs/ directory of this repository as follows:

./make html

The particular application must be selected by un-commenting the appropriate app_name variable at the top of the file docs/conf.py.

4. Examples

The following command will generate HTML output for the quoFEM application in the directory build/quoFEM/html/:
```
make qfem html
```
The following command will generate HTML output for the WE-UQ application in the directory ../WE-UQ-Documentation/WE-UQ/html/:
```
make we web
```
Note: this will write / modify files that are located outside of the documentation repository!
The following command will generate latex and pdf output for the R2D application in the directories build/R2D/latex/, and build/R2D/pdf/, respectively:
```
make r2d latex pdf
```
Note, however, that in order to achieve a proper build, one may need to run the make <app> latex target several times in succession before running make <app> pdf.
It is often useful to clean and update the documentation when building, as some changes in other repositories can affect this one. The following command will clean the documentation and update the source files before building the HydroUQ application's example cases. Some example files may be in the individual app repositories, e.g. ../HydroUQ/Examples/, so it is recommended to download them locally. Within the SimCenterDocumentation root folder, run
```
cd ..
git clone https://github.com/NHERI-SimCenter/HydroUQ.git
cd ./SimCenterDocumentation/docs
make clean
cd ..
make update
make hydro examples
make hydro html
```

Note: Legacy build scripts in the docs directory do not sync example files from their source repositories.

snaeimi / simcenterdocumentation Goto Github PK