Contributing to the Documentation

Documentation changes should generally be developed off master (a hotfix). You should check in on the #cdmsbats-documentation channel before starting.

Rarely, if you are updating documentation based on new features on develop - like updated build instructions for a new build system - you should develop your documentation off develop (a feature).

Releasing documentation quickly is critical. Prefer frequent documentation releases. Because cdmsbats version follow semantic versioning, a documentation release increments the lowest number. If you are uneasy releasing cdmsbats, contact Aditi for help.

As always, if you are working with others on changes, you should git pull frequently. If you are unsure how to do this you should contact Aditi Pradeep for help.

BatCommon documentation is configured in the mkdocs.yml file found in the parent directory. All the contents that go into the webpage are configured in a bunch of markdown (.md) files inside BatCommon/docs. To figure out which of these files point to what page in the documentation, please refer to the mkdocs.yml file which contains this information. To edit contents in an existing file, simply open the file and make the changes that you desire. Then you must commit and push the changes to the repository by doing:

git add <filename>
git commit -m "<A message describing what changes you'll be commiting>"
git push origin feature/batcommon_documentation

If you wish to create a new page in the documentation, you must first create a new markdown(.md) file in BatCommon/docs. Add the information you want into this file and save. In addition, you must go to the mkdocs.yml file and configure the page with proper spacing and intendations. For e.g. if you want to create a subpage called Contribution, create a file with a suitable name (say contribution.md) in the docs folder and add your contents. Then open the mkdocs.yml file and add a new line '-Contribution: contribution.md` (you may use the already available page configuration in the file as examples since it is pretty straight forward). Then save, add, commit and push all the changes you've made. Make sure that the spacing and filenames are accurate in the mkdoc.yml file since this file is notorious for these things. If at any point you have any questions or need help please contact Aditi Pradeep for help. You can reach her via slack using @aditi. You may additionally find help in the cdmsbats-documentation slack channel.