Documentation

Important

Documenting the project, changes and designs are just as important as what's being built.

In 12 months time do you think you'll remember where you were at, what about new contributors?

Location and Customisation

All project documentation lives in the projects 'docs' directory and written in mark-down format that's easy to update, especially with tools like VSCode.

docs
├── authors.md
├── changelog.md
├── dev
│   ├── contributing.md
│   ├── documentation.md
│   ├── getting_started.md
│   ├── makefile.md
│   └── python.md
├── helpwanted.md
├── img
│   └── screenshot.png
├── index.md
└── license.md

See mkdocs-material documentation for more information.

Build documentation

make build-docs

Will compile all documentation and generate the site directory containing the html documentation this can be viewed locally.

Note

The site directory is not included in source control as is dynamically generated.

Viewing Locally

To view or update locally

make docs-serve

This will start up the mkdocs local server and your projects documentation will be available in your browser.

http://localhost:8000

Making changes

Any changes to the document files or mkdocs.yml will be automatically updated when being displayed locally, with a page refresh, on the local server view each time you save, so allows you to see the changes as you make them.

Adding Diagrams using Mermaid

See official mermaid documentation for further instructions on how to make a diagrams.

```mermaid
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]
```

graph TD A[Client] --> B[Load Balancer] B --> C[Server01] B --> D[Server02]

mkdocs.yml Contents

# project information
site_name: "Maker Hub"
site_author: "Stephen Eaton"
site_description: "Parts, Project builds and more for Makers"

# Page Tree
nav:
  - Home: index.md
  - Development:
      - dev/getting_started.md
      - dev/documentation.md
      - dev/makefile.md
      - dev/python.md
      - dev/docker.md
      - dev/contributing.md

  - Contributors: authors.md
  - Change Log: changelog.md
  - License: license.md
  - Help Wanted: helpwanted.md

# Configuration
theme:
  favicon: img/favicon.ico
  logo: img/logo.svg
  name: material
  features:
    - navigation.tabs
    - navigation.indexes
    - navigation.expand
    - header.autohide

# Repository
repo_name: "madeinoz67/maker-hub"
repo_url: "https://github.com/madeinoz67/maker-hub"
edit_uri: ""

# plugins
plugins:
  - search
  - mermaid2

# extensions
markdown_extensions:
  - abbr
  - attr_list
  - admonition
  - footnotes
  - meta
  - pymdownx.details
  - pymdownx.snippets
  - pymdownx.smartsymbols
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tabbed
  - pymdownx.tilde
  - pymdownx.highlight
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid
  - pymdownx.keys
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji # noqa


      emoji_generator: !!python/name:materialx.emoji.to_svg # noqa


# Copyright
copyright: Copyright &copy; 2021-2022 Stephen Eaton
# footer customisation
extra:
  social:
    - icon: fontawesome/brands/github
      link: "https://github.com/madeinoz67"
    - icon: fontawesome/brands/gitlab
      link: "https://gitlab.com/madeinoz67"
    - icon: fontawesome/brands/twitter
      link: "https://twitter.com/madeinoz"