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:
- Download repository: Download the GitHub repository (which contains both the code and documentation files): Use this link to download a ZIP file.
- Extract: Extract (unzip) the ZIP file.
- 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/
- 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:
- 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
- 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