Skip to content

Commit cb0fbfd

Browse files
authored
amrex-tutorials docs sphinx build instructions (#167)
1 parent 72c44ec commit cb0fbfd

File tree

1 file changed

+51
-0
lines changed

1 file changed

+51
-0
lines changed

Docs/Readme.sphinx

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
To update the online AMReX-Tutorials documentation using sphinx:
2+
3+
1. Checkout the main branch of amrex-tutorials
4+
5+
2. Go to amrex-tutorials/Docs/source and edit the relevant .rst file(s).
6+
7+
3. Commit/push your changes.
8+
9+
The GitHub action script will build the html pages and commit them to AMReX-Tutorials' gh-pages repo for you. If you would like to
10+
preview the html locally, you can:
11+
12+
4. Go back into amrex-tutorials/Docs.
13+
14+
5. Type "make html". This will build new html files in amrex-tutorials/Docs/build/html
15+
16+
**********************************************************************************
17+
18+
If you would like to build the web pages locally, you will need Python, the Sphinx software, and the "Read the Docs" theme.
19+
20+
If you have conda, you can install the necessary packages as follows:
21+
22+
1. Type "conda install sphinx"
23+
24+
2. Type "conda install sphinx_rtd_theme"
25+
26+
If you don't have a conda Python installation, you get one by doing the following:
27+
28+
1. Go to https://conda.io/miniconda.html and download the Python 3.6 64-bit (bash installer), "Miniconda3-latest-Linux-x86_64.sh". Save this script to your hard drive.
29+
30+
2. Type "bash Miniconda3-latest-Linux-x86_64.sh" and follow the installation prompts.
31+
32+
3. The install script will prompt you to add some commands to your .bashrc that add the miniconda install location to your PATH environment variable.
33+
If Bash is your default shell, choose "yes". Otherwise, you will need to manually do the same for your shell of choice.
34+
35+
4. Either open a new terminal, or re-source the configuration file you just added to. E.g., for bash:
36+
source ~/.bashrc
37+
38+
You should now be able to successfully "make html" in amrex-tutorials/Docs.
39+
40+
If you would like to make a pdf document from the *rst files, first
41+
42+
sudo apt-get install latexmk
43+
(if you are using macOS, latexmk is installed via the TexLive Utility)
44+
45+
Then in the amrex-tutorials/Docs directory, type
46+
47+
make latexpdf
48+
(if you have the slimmed-down latex install, then you need to also install the following packages via TexLive Utility: tabulary, varwidth, framed, wrapfig, capt-of, needspace, courier)
49+
50+
51+
This will create amrex-tutorials/Docs/build/latex/amrex.pdf

0 commit comments

Comments
 (0)