Creating Documentation

Creating the PPG-beats documentation.

---

Create and preview the documentation locally

Pre-requisites:

• MkDocs: MkDocs is a 'static site generator that's geared towards building project documentation (from mkdocs.org). Installation instructions are available here. e.g. on my Mac, I installed MkDocs using the following command: pip install mkdocs

Steps:

1. Download repository: Download the GitHub repository (which contains both the code and documentation files): Use this link to download a ZIP file.
2. Extract: Extract (unzip) the ZIP file.
3. Set current directory: Go to Command Prompt (on Windows) or Terminal (on MacOS). Set the current directory to the extracted folder. e.g. on my Mac, I use: cd /Users/petercharlton/Documents/GitHub/ppg-beats/
4. Preview documentation: Use the mkdocs serve command to view the documentation in your browser at http://127.0.0.1:8000/.

Upload the documentation to the web

Pre-requisites:

• GitHub: A GitHub account (and preferably some experience with GitHub).
• Read the Docs: A Read the Docs account (although this can be easily set up, and no experience is required).

Steps:

1. Upload to GitHub: Commit the documentation to a GitHub repository. e.g. in my case, peterhcharlton/ppg-beats. Note that the documentation is committed to the main branch. It contains:
   • a file named mkdocs.yml in the main folder
   • a subfolder named docs which contains markdown documentation
   • a subfolder named source which contains the source code
2. Host on Read the Docs: Host the documentation on Read the Docs, allowing it to be viewed as a website. e.g. the PPG-beats documentation is hosted by Read the Docs here. The following are helpful for working out how to do this:
   • Read the Docs Tutorial: Provides details of how to host content stored in a GitHub repository.
   • MkDocs 'Deploying your docs' guide