fix: fix bugs (#197)

* ci: fix typo * chore: remove old files * chore: update readme * chore: fix typo
2026-01-06 10:13:36 -08:00 · 2022-03-29 20:37:23 +08:00
parent 1ca06a3097
commit 032b6ce4a1
6 changed files with 68 additions and 214 deletions
--- a/templates/Example_Documentation-template.md
+++ b/templates/Example_Documentation-template.md
--- a/.github/workflows/recreate_on_push.yaml
+++ b/.github/workflows/recreate_on_push.yaml
@@ -5,40 +5,39 @@ name: Create offline documentation

 on:
  push:
-    branches: [ master ]
+    branches: [master]
  workflow_dispatch:

 jobs:
  build:
-
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.8]

    steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install setuptools wheel
-        pip -r requirements.txt
-    - name: Run mkdocs --clean
-      run: |
-        mkdocs build --clean
-        
-    - name: Upload pdf 
-      uses: actions/upload-artifact@v2
-      with:
-        name: artifact
-        path: site/pdf/document.pdf
-        
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools wheel
+          pip install -r requirements.txt
+      - name: Run mkdocs --clean
+        run: |
+          mkdocs build --clean
+
+      - name: Upload pdf
+        uses: actions/upload-artifact@v2
+        with:
+          name: artifact
+          path: site/pdf/document.pdf
+
  Deploy:
-    needs: [ build ]
+    needs: [build]
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
--- a/README.md
+++ b/README.md
@@ -2,6 +2,12 @@

 [![Create offline documentation](https://github.com/armbian/documentation/actions/workflows/recreate_on_push.yaml/badge.svg)](https://github.com/armbian/documentation/actions/workflows/recreate_on_push.yaml)

+<p align="center">
+  <a target="_blank" href="https://docs.armbian.com">
+    <img alt="logo" src="./docs/images/logo.png">
+  </a>
+</p>
+
 ## Overview

 Documentation is written in [markdown](https://www.markdownguide.org/basic-syntax/) and stored in the `docs/` subfolder.  Images go in `docs/images`.
@@ -10,14 +16,18 @@ This repo is meant for storing and quick glances.  Official output is [https://d

 Armbian Documentation is available in the following formats:

-* mkdocs site [https://docs.armbian.com](https://docs.armbian.com),
-* [PDF user guide](https://github.com/armbian/documentation/raw/master/document.pdf).
+* [Official document website](https://docs.armbian.com),
+* [PDF document](https://github.com/armbian/documentation/raw/master/document.pdf)

-Armbian Documentation relies on a file naming convention:
+## Contributing

-`Parent-Topic-Name_Child-Topic-Name.md`
+This site is built with [mkdocs](https://github.com/mkdocs/mkdocs/) and depends on [mkdocs-material](https://github.com/squidfunk/mkdocs-material).

-Parent-Topic-Name and Child-Topic-Name are separated by an underscore `_`.  Hyphens `-` are automatically converted to spaces.
+Armbian Documentation naming of document files follows this rules:
+
+`[Parent-Topic-Example]_[Child-Topic]-example.md`
+
+`Parent-Topic-Name` and `Child-Topic-Name` are separated by an underscore `_`.  Hyphens `-` are automatically converted to space.

 Please try to avoid creating new parent topics unless absolutely necessary.

@@ -30,64 +40,36 @@ Current Parent Topics:
 * Release management
 * Community

-## .gitignore
-For easier testing and commits `.gitignore` is configured to ignore `site/`
+See the [document template](.github/DOCUMENT_TEMPLATE.md) before you writing any content.

-`mkdocs.yml` should probably be added, but we can commit for now
+## Working on the content

-## Required packages
+```bash
+git clone https://github.com/armbian/documentation
+pip install -r requirements.txt
+mkdocs build --clean && mkdocs serve
+```

-The documentation build process will require the following packages:
-
-* `git`
-* `python-jinja2`
-* `mkdocs`
-
-Install these on the development host using:
-
-`sudo apt-get install -y -qq git python-jinja2 mkdocs`
-
-
-## Tools
-
-### mkArmbianDocs.py
-generates mkdocs.yml file based on contents of `docs/`
-
-* command-line options for input and output directories
-* requires the `python-jinja2` module which may not be installed by default
-* not needed unless making changes to the structure of the documentation
-* see `mkArmbianDocs.py -h` for help
-
-### Missing tools
-The following capabilities are not yet available:
-
-* html2doc output to PDF user manual
-
-## Generating
-From the parent folder of the repo, run:
-
-`tools/mkArmbianDocs.py && mkdocs build`
-
-This will generate the mkdocs.yml configuration file and then generate the mkdocs site to the `site/` folder.
-
-## Testing
-To preview locally, execute the preview server: `mkdocs serve`. You will be able to make edits to existing files and observe the results in real time.
+You will be able to make edits to existing files and observe the results in real time.

 After changing text in an existing file, use this command to rebuild and view the documentation:

 `mkdocs build --clean && mkdocs serve`

-After adding a new file, either hand-edit `mkdocs.yml`, or rerun `tools/mkArmbianDocs.py`.
+After adding a new file, either hand-edit `mkdocs.yml`, or re-run `tools/mkArmbianDocs.py` **unless making changes to the structure of the `docs/` folder**. (See below)

-## Quick Start
+## Generate tools

-```bash
-pip install mkdocs
-git clone https://github.com/armbian/documentation
-#vim docs/[Parent Topic Example]-child-topic-example.md
-#generate config, build, launch local preview server
-tools/mkArmbianDocs.py && mkdocs build --clean && mkdocs serve
-git add docs/*.md
-git commit -m "added new howto on exampling"
-git push
-```
+### mkArmbianDocs.py
+Generate `mkdocs.yml` based on the contents of `docs/` folder
+
+* Command-line options for input and output directories
+* Requires install requirement
+* You don't need to run it every time unless making changes to the structure of the `docs/` folder
+* See `mkArmbianDocs.py -h` for help
+
+From the parent folder of the repo, run:
+
+`python3 tools/mkArmbianDocs.py && mkdocs build`
+
+This will generate the `mkdocs.yml` and publish built HTML to the `site/` folder.
--- a/readthedocs_custom/armbian-navbar.html
+++ b/readthedocs_custom/armbian-navbar.html
@@ -1,11 +0,0 @@
-<div
-id="mega-menu-wrap-header-menu" class="mega-menu-wrap"><div class="mega-menu-toggle" tabindex="0"><div class='mega-toggle-block mega-menu-toggle-block mega-toggle-block-right mega-toggle-block-1' id='mega-toggle-block-1'></div></div><ul id="mega-menu-header-menu" class="mega-menu mega-menu-horizontal mega-no-js" data-event="hover" data-effect="fade" data-effect-speed="200" data-second-click="go" data-document-click="collapse" data-reverse-mobile-items="true" data-vertical-behaviour="standard" data-breakpoint="600"><li class='mega-menu-item mega-menu-item-type-custom mega-menu-item-object-custom mega-align-bottom-left mega-menu-flyout mega-hide-arrow mega-hide-text mega-menu-item-3656' id='mega-menu-item-3656'><a class="dashicons-admin-home mega-menu-link" href="https://www.armbian.com/" tabindex="0"> Armbian home</a></li>
-<li class='mega-menu-item mega-menu-item-type-post_type mega-menu-item-object-page mega-align-bottom-left mega-menu-flyout mega-hide-arrow mega-menu-item-3657' id='mega-menu-item-3657'><a class="mega-menu-link" href="https://www.armbian.com/download/" tabindex="0">Download</a></li>
-<li class='mega-menu-item mega-menu-item-type-post_type mega-menu-item-object-page mega-current-menu-item mega-current_page_item mega-align-bottom-left mega-menu-flyout mega-hide-arrow mega-menu-item-4941' id='mega-menu-item-4941'><a class="mega-menu-link" href="https://docs.armbian.com/" tabindex="0">Documentation</a></li>
-<li class='mega-menu-item mega-menu-item-type-custom mega-menu-item-object-custom mega-align-bottom-left mega-menu-flyout mega-menu-item-5049' id='mega-menu-item-5049'><a class="mega-menu-link" href="https://github.com/igorpecovnik/lib" tabindex="0">Sources</a></li>
-<li class='mega-menu-item mega-menu-item-type-custom mega-menu-item-object-custom mega-align-bottom-left mega-menu-flyout mega-menu-item-3663' id='mega-menu-item-3663'><a class="mega-menu-link" href="https://forum.armbian.com" tabindex="0">Forum</a></li>
-<li class='mega-menu-item mega-menu-item-type-custom mega-menu-item-object-custom mega-menu-item-has-children mega-align-bottom-right mega-menu-flyout mega-hide-arrow mega-item-align-right mega-menu-item-3667' id='mega-menu-item-3667'><a class="mega-menu-link" href="https://www.armbian.com/donate/" tabindex="0">Donate</a>
-<ul class="mega-sub-menu">
-<li class='mega-menu-item mega-menu-item-type-post_type mega-menu-item-object-page mega-menu-item-4223' id='mega-menu-item-4223'><a class="dashicons-smiley mega-menu-link" href="https://www.armbian.com/donors/">Thanks</a></li></ul>
-</li></ul></div>
-
--- a/readthedocs_custom/base.html
+++ b/readthedocs_custom/base.html
@@ -1,119 +0,0 @@
-<!DOCTYPE html>
-<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
-<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
-<head>
-  <meta charset="utf-8">
-  <meta http-equiv="X-UA-Compatible" content="IE=edge">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  {% if page_description %}<meta name="description" content="{{ page_description }}">{% endif %}
-  {% if site_author %}<meta name="author" content="{{ site_author }}">{% endif %}
-  {% block htmltitle %}
-  <title>{% if page_title %}{{ page_title }} - {% endif %}{{ site_name }}</title>
-  {% endblock %}
-
-  {% if favicon %}<link rel="shortcut icon" href="{{ favicon }}">
-  {% else %}<link rel="shortcut icon" href="{{ base_url }}/img/favicon.ico">{% endif %}
-
-  {# CSS #}
-  <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
-
-  <link rel="stylesheet" href="{{ base_url }}/css/theme.css" type="text/css" />
-  <link rel="stylesheet" href="{{ base_url }}/css/theme_extra.css" type="text/css" />
-  <link rel="stylesheet" href="{{ base_url }}/css/highlight.css">
-  {%- for path in extra_css %}
-  <link href="{{ path }}" rel="stylesheet">
-  {%- endfor %}
-
-  {% if current_page %}
-  <script>
-    // Current page data
-    var mkdocs_page_name = "{{ page_title }}";
-    var mkdocs_page_input_path = "{{ current_page.input_path }}";
-    var mkdocs_page_url = "{{ current_page.abs_url }}";
-  </script>
-  {% endif %}
-  <script src="{{ base_url }}/js/jquery-2.1.1.min.js"></script>
-  <script src="{{ base_url }}/js/modernizr-2.8.3.min.js"></script>
-  <script type="text/javascript" src="{{ base_url }}/js/highlight.pack.js"></script>
-  <script src="{{ base_url }}/js/theme.js"></script>
-
-  {%- block extrahead %} {% endblock %}
-
-  {%- for path in extra_javascript %}
-  <script src="{{ path }}"></script>
-  {%- endfor %}
-
-  {% if google_analytics %}
-  <script>
-      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
-      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
-      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
-      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
-
-      ga('create', '{{ google_analytics[0] }}', '{{ google_analytics[1] }}');
-      ga('send', 'pageview');
-  </script>
-  {% endif %}
-</head>
-
-<body class="wy-body-for-nav" role="document">
-
-  <div class="wy-grid-for-nav">
-
-    {# SIDE NAV, TOGGLES ON MOBILE #}
-    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
-      <div class="wy-side-nav-search">
-        <a href="{{ homepage_url }}" class="icon icon-home"> {{ site_name }}</a>
-        {% include "searchbox.html" %}
-      </div>
-
-      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
-        <ul class="current">
-          {% for nav_item in nav %}
-            <li>{% include "toc.html" %}<li>
-          {% endfor %}
-        </ul>
-      </div>
-      &nbsp;
-    </nav>
-
-    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
-
-      {# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #}
-      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
-        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
-        <a href="{{ homepage_url }}">{{ site_name }}</a>
-      </nav>
-
-      {# PAGE CONTENT #}
-      {% include "armbian-navbar.html" %}
-      <div class="wy-nav-content">
-        <div class="rst-content">
-          {% include "breadcrumbs.html" %}
-          <div role="main">
-            <div class="section">
-              {% block content %}
-                {{ content }}
-              {% endblock %}
-            </div>
-          </div>
-	  {%- block footer %}
-          {% include "footer.html" %}
-	  {% endblock %}
-        </div>
-      </div>
-
-    </section>
-
-  </div>
-
-{% include "versions.html" %}
-
-</body>
-</html>
-{% if current_page and current_page.is_homepage %}
-<!--
-MkDocs version : {{ mkdocs_version }}
-Build Date UTC : {{ build_date_utc }}
-->
-{% endif %}
--- a/tools/mkArmbianDocs.py
+++ b/tools/mkArmbianDocs.py
@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 """
-    Copyright Armbian (c) 2021
+    Copyright Armbian (c) 2022
 """

 import fnmatch
@@ -18,7 +18,8 @@ def parse_arguments():
    import argparse
    parser = argparse.ArgumentParser(
        description='generate mkdocs.yml based on file naming covention: [ParentCategory]-Subtopic.md')
-    parser.add_argument('-v', '--verbose', action='store_true', help='increase output verbosity')
+    parser.add_argument('-v', '--verbose', action='store_true',
+                        help='increase output verbosity')
    parser.add_argument('-i', '--indir', metavar='INPUT_DIRECTORY', default='./docs',
                        help='directory containing markdown files [default: ./docs]')
    parser.add_argument('-o', '--outdir', metavar='OUTPUT_DIRECTORY', default='./',
@@ -52,8 +53,9 @@ def parseFiles(validFileList, indir):

    parsedFileList = dict()
    tocTree = defaultdict(set)
-    tocRegex = re.compile(r"(?P<parent>[\w-]+?(?=_))_(?P<child>[\w-].*(?=\.md))")
-    ##FIXME add Try catch or finaly
+    tocRegex = re.compile(
+        r"(?P<parent>[\w-]+?(?=_))_(?P<child>[\w-].*(?=\.md))")
+    # FIXME add Try catch or finaly
    for file in sorted(validFileList):
        filepath = os.path.join(indir, file)
        log.info("trying to match %s ", file)
@@ -147,7 +149,8 @@ nav:


 def writeSiteFile(content, outdir):
-    assert os.path.isdir(outdir), "Provided output directory path is not a directory"
+    assert os.path.isdir(
+        outdir), "Provided output directory path is not a directory"

    file = "mkdocs.yml"
    filepath = os.path.join(outdir, file)