python docs should now appear in mdBook

Author: calbaker

.github/workflows/deploy-book.yaml

@@ -8,6 +8,7 @@ on:
       - "docs/**"
       - ".github/workflows/deploy-book.yaml"
       - "README.md"
+      - "python/**"
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -33,11 +34,18 @@ jobs:
       MDBOOK_VERSION: 0.4.21
     steps:
       - uses: actions/checkout@v3
-      - name: Install mdBook
+      - name: Install mdBook and supporting dependencies
         run: |
           curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
           rustup update
           cargo install --version ${MDBOOK_VERSION} mdbook
+      - name: Build python docs
+        run: 
+          sudo apt update
+          sudo apt install pipx
+          pipx ensurepath
+          pipx install pydoc-markdown
+          pydoc-markdown -I python/ -p fastsim --render-toc > docs/src/python_docs.md          
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v3

docs/src/SUMMARY.md

@@ -4,5 +4,6 @@
 - [Documentation](./doc.md)
     - [Rust API](./doc/rust.md)
         - [Rail Network](./doc/rail-network.md)
+    - [Python API](./doc/python-doc.md)
 - [Press Releases](./press-releases.md)
 - [How to Update This Book](./how-to-update.md)

docs/src/doc.md

@@ -1 +1,5 @@
-# Documentation
+# Documentation
+
+## [Python](./doc/python-doc.md)
+
+## [Rust](./doc/rust.md)

docs/src/doc/python-doc.md

@@ -0,0 +1 @@
+# Python API Documentation

docs/src/how-to-update.md

@@ -4,12 +4,21 @@
 
 ## Setup
 
-1. If not already done, [install mdbook](https://rust-lang.github.io/mdBook/guide/installation.html)
+If not already done, [install mdbook](https://rust-lang.github.io/mdBook/guide/installation.html)
 
-## Publishing
 
+## Serving locally
+Run th following in the repository root directory: 
+1. If any python files were modified, 
+    1. Install [pipx](https://github.com/pypa/pipx#install-pipx)
+    1. Install [pydoc-markdown](https://niklasrosenstein.github.io/pydoc-markdown/#installation-)
+    1. run `pydoc-markdown -I python/ -p fastsim --render-toc > docs/src/python_docs.md`. Do not modify this file manually. 
+1. Run `mdbook serve --open docs/`
+
+
+## Publishing
 1. Update `book.toml` or files in `docs/src/`
-1. Make sure the docs look good locally: `mdbook build docs/ --open`
+1. Make sure the docs look good locally by running the steps in [Serving Locally](#serving-locally)
 1. Commit files and push to `main` branch
 
 After that, a GitHub action will build the book and publish it [here](https://pages.github.nrel.gov/MBAP/mbap-computing/)