docs/build.md

   1 # For Editors of the Docs
   2
   3 ## Files
   4
   5     git clone https://github.com/openwfm/WRF-SFIRE
   6     cd WRF-SFIRE
   7
   8     .readthedocs.yaml`    # ReadTheDocs configuration file
   9     mkdocs.yml            # MkDocs configuration file.
  10     docs/
  11          requirements.in  # PIP configuration file.
  12          requirements.txt # PIP configuration file.
  13          index.md         # The documentation homepage.
  14          ...              # Other markdown pages, images and other files.
  15
  16 ## Build the software
  17
  18 The docs in the `master` branch of
  19 [https://github.com/openwfm/WRF-SFIRE](https://github.com/openwfm/WRF-SFIRE)
  20 are displayed at [https://wrf-sfire.readthedocs.io](https://wrf-sfire.readthedocs.io)
  21
  22 You can preview the docs in your own copy or in other branches locally as follows. First install mkdocs (once):
  23
  24      conda create -n mkdocs python=3.12
  25      conda activate mkdocs
  26      pip install -r docs/requirements.txt
  27
  28 ## Commands
  29
  30 Every time:
  31
  32    conda activate mkdocs
  33    mkdocs build  #  Build the documentation site.
  34
  35 and open the file site/index.html. This is far from perfect, though; if clicking on a link gives you a directory,
  36 open file index.html in that directory.
  37
  38 Other commands available:
  39
  40   mkdocs serve # Start the live-reloading docs server.
  41   mkdocs -h    #  Print help message and exit.
  42
  43 For full documentation visit [mkdocs.org](https://www.mkdocs.org).
  44
  45 ##  How to edit
  46
  47 ### Make your own branch
  48
  49 If you are contributing code, make your own branch as you normaly would per the instructions elsewhere
  50 (usually off the develop or release branch) and make changes in the documentation
  51 to document your changed code.
  52
  53 When you are contributing to the docs only and do not change the code, make a new branch off the `master`
  54 branch and give it a name indicating this is a documentation change, such as `docs-`something.
  55
  56 ### Edit the docs
  57
  58 Chapters are Markdown files in directory `docs`.
  59 The navigation bar on the left (or a pancake when viewing the site on a small screen) is created from the
  60 `nav:` section at the bottom of file `mkdocs.yml`. When you add a new Markdown file, you need to add also a corresponding line there.
  61
  62 ### Graphics
  63
  64 Please reduce the resolution of images and do not commit any large files.
  65 Large binary files like images bloat the repository size forever,
  66 even of they are replaced or deleted in later commits.
  67
  68 ### Submit your changes
  69
  70 Merge the branch you started from into your branch and resolve any conflicts.
  71 Then test the result. Merge again in case anything
  72 changed in the meantime. If nothing changed, you can make a pull request
  73 on Github.
  74
  75 ## Resources
  76
  77 https://www.markdownguide.org
  78
  79 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  80