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