Fix build issues for docs and added notes about nav (#24)

Author: timlinux

docs/mkdocs-base.yml

@@ -44,46 +44,44 @@ nav:
                 - Code of Conduct: about/code-of-conduct.md
                 - Running Instances: about/running-instances.md
         - Users:
-                - Overview: 
-                        - Quickstart: 
-                        - user/index.md
-                                - user/quickstart/index.md
-                        - Guide:
-                                - user/guide/index.md
-                                - Disclaimer: about/disclaimer.md
-                                - License: about/license.md
-                        - Manual: 
-                                - user/manual/index.md
-                                - Home Page: user/manual/home.md
+                - user/index.md
+                - Quick Start: 
+                        - user/quickstart/index.md
+                - Guide:
+                        - user/guide/index.md
+                        - Disclaimer: about/disclaimer.md
+                        - License: about/license.md
+                - Manual: 
+                        - user/manual/index.md
+                        - Home Page: user/manual/home.md
         - Administrators:
-                        - Guide:
-                        - administrator/index.md
-                        - Manual:
-                                - administrator/guide/index.md
-                                - administrator/manual/index.md
+                - administrator/index.md
+                - Guide:
+                        - administrator/guide/index.md
+                - Manual:
+                        - administrator/manual/index.md
         - Developers:
-                        - developer/index.md
-                                - developer/api/index.md
-                        - API:
-                                - Reference: developer/api/manual/index.md
-                                - Guide: developer/api/guide/index.md
-                        - Guide:
-                                - Overview: developer/guide/index.md
-                                - Architecture: developer/guide/architecture.md
-                                - Prerequisites: developer/guide/prerequisites.md
-                                - Design: developer/guide/design.md
-                                - IDE Setup: developer/guide/ide-setup.md
-                                - Cloning: developer/guide/checking-out-the-code.md
-                                - Configuration: developer/guide/configuration.md
-                                - Building: developer/guide/building.md
-                                - Road Map: developer/guide/roadmap.md
-                                - Workflows: developer/guide/developer-workflows.md
-                                - "": developer/guide/templates/pull-request-template.md 
-                                - "": developer/guide/templates/commit-message-convention.md
-                        - Documentation: developer/documentation/index.md
-                        - Manual:
-                                - developer/manual/index.md
-                        - License: about/license.md
+                - developer/index.md
+                - API:
+                        - developer/api/index.md
+                        - Reference: developer/api/manual/index.md
+                        - Guide: developer/api/guide/index.md
+                - Guide:
+                        - Overview: developer/guide/index.md
+                        - Architecture: developer/guide/architecture.md
+                        - Prerequisites: developer/guide/prerequisites.md
+                        - Design: developer/guide/design.md
+                        - IDE Setup: developer/guide/ide-setup.md
+                        - Cloning: developer/guide/cloning.md
+                        - Configuration: developer/guide/configuration.md
+                        - Building: developer/guide/building.md
+                        - Road Map: developer/guide/roadmap.md
+                        - Workflows: developer/guide/workflows.md
+                        - "": developer/guide/templates/pull-request-template.md 
+                        - "": developer/guide/templates/commit-message-convention.md
+                - Documentation: developer/documentation/index.md
+                - Manual: developer/manual/index.md
+                - License: about/license.md
         - DevOps: 
                 - devops/index.md
                 - Guide: devops/guide/index.md

docs/python_manual_hook.py

@@ -22,18 +22,19 @@ def on_startup(command, dirty):
     	"migrations",
         "tests"]
     for root, dirs, files in os.walk("../django_project"):
-            file = os.path.join(root, file)
-            ignored = False;
-            if file.endswith(".py"):
-                for item in ignore_list:
-                    if item in file:
-                        ignored = True;
-                    #print (item, file, ignored)
-                if not ignored:
-                    file = file.replace("../django_project/", "::: ")
-                    file = file.replace("/", ".")
-                    file = file.replace(".py", "")
-                    template = template + file + "\n"
+        for file in files:
+             file = os.path.join(root, file)
+             ignored = False;
+             if file.endswith(".py"):
+                 for item in ignore_list:
+                     if item in file:
+                         ignored = True;
+                     #print (item, file, ignored)
+                 if not ignored:
+                     file = file.replace("../django_project/", "::: ")
+                     file = file.replace("/", ".")
+                     file = file.replace(".py", "")
+                     template = template + file + "\n"
+    file = open("src/developer/manual/index.md","wt")
     file.write(template)
-    file = open("docs/src/developer/manual/index.md","wt")
     file.close()

docs/src/developer/documentation/index.md

@@ -304,6 +304,7 @@ Once your pull request is opened you need to wait for it to be merged before you
 
 ## Creating new files
 
+### Page metadata
 Whenever you create a new file, you should add the standard header to the top of the file:
 
 ```
@@ -324,6 +325,21 @@ The summary can be updated to include your name for documents you contribute to.
 
 The context_id is used to create a unique permalink to this document, and is optional. See further down in this document for more details.
 
+### Navigation
+
+All pages need to be added to the 'Nav' section of the `mkdocs-base.yml` file. This will ensure that it is available in the menus and that mkdocs renders without errors. For example, if you wish to add a new page to the User Guide area, in Nav you would add a line like this:
+
+
+`- "Navigating the map": users/guide/map-navigation.md`
+
+Sometimes you may not wish to have the new page displayed in the menu system (this can be useful when, for example, it is accessed via a link in another page. In these cases, leave the menu entry part blank e.g.
+
+`- "": users/guide/map-navigation.md`
+
+
+Mkdocs will still generate the page but it will not be added to the menu.
+
+
 ## Technical notes
 
 ### Working locally