How I used Python to Collect Project Documentation

site_name: firstSite nav:     
- Home: index.md
- About: about.md
image copied from the MkDocs page here https://www.mkdocs.org/

Using My Sample Project

.
├── LICENSE
├── README.MD
├── generated-site
│ ├── base.yml
│ └── docs
│ └── index.md
├── package.json
└── site.py
  • The generated-site folder has the main files and folders that MkDocs will use to generate the site. When our scripts run, this docs folder will also create a site-files folder to hold the markdown files that MkDocs will use.
  • The index.md is sitting inside the docs folder for convenience, and to use as a home page for the generated site. You can just leave this file blank because it’s just as a landing page.
  • The base.yml file will be used by the python script to create a custom yaml file for MkDocs to use when creating the site. As the python script runs, it will write values to this file. The file I’ve created includes the material theme, but you can customize this for your project if you wanted to.
  • I used npm init to create the package.json at the project’s root. If you want to use this for your project, you’ll need to change the values for author, project, etc. to suit your needs. The npm scripts that I’ve included inside this file also allow us to build and deploy our project.
  • The site.py file is the python script which I will cover in the next section.

Creating the Python Script

  • delete_files_and_folders() — deletes any files and folders that were generated from the last run of the script
  • create_files_and_folders() — creates any files and folders that are necessary for copying and building the structure for MkDocs
  • select_md — selects the markdown files from the locally downloaded copy of your GitHub project
  • copy_md — copies the markdown files and writes their values into the markdown.yml file so that MkDocs can use the files and yaml to create the site

Using the NPM Scripts

  • github-clone — clones the GitHub project you want to gather documentation from (in this case its Angular Material)
  • github-delete — deletes the local copy of your GitHub project
  • install-dependencies — installs MkDocs and the material theme with python’s pip (per the getting started guide)
  • build — builds the project and serves it locally
  • deploy — deploys the project to the repo’s GitHub pages site

Closing Thoughts

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store