feat: docs - read notes

With this release I've completely finished my goals for the documentation tools.
I've also fixed some more parsing errors that were around the docs.
The source code comment parser was completely rewritten because:
- I didn't like the way it just dumped all links on a single page. That is okay for a handful of files, but  not anymore.
- With the current size e of SRL-T and WaspLib I think having things into their own sections (which are the same as their directories) makes it easier to navigate.
This thing was and still is written in python. I've read some python in the past but never actually used it for anything until I started modifying the docs tool.
This means:
- The doc tool is probably poorly written. I know for a fact that it's doing more loops than it should have to but it was just easier for me this way and it works which is what matters most.
- There could be bugs. I tested it in both SRL-T and WaspLib documentation and it seems to work fine but I'm not sure there aren't some weird cases.

With that said, the way it works now is:
- each file that has doc comments will have it's own html page created.
- each root directory that has doc pages under it will have a index file created for those pages, let's call them main folder indices.
If a file with documentation matches a main folder index page, it's documentation will be added at the top of that page.
  - For example, optional.simba currently have docs, it's comments are added to the optional page, and at the bottom of the page you have your index to each of the optional files that are documented
- a final index page is created indexing each of the main folder indices.
The final result is pretty neat and organized. All tools under the tools sections, all utils under the utils section, all osr files under the osr section and all otpional docs under the otpional section.

.github/workflows/docs.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Generate Documentation
         run: |
           sudo apt-get install python3 python3-pip
-          sudo pip3 install sphinx furo myst-parser sphinx-copybutton linkify-it-py sphinx-togglebutton
+          sudo pip3 install sphinx furo myst-parser sphinx-copybutton linkify-it-py sphinx-togglebutton sphinxemoji
           cd docs/docgen/
           python3 docgen.py ../../
 

docs/docgen/conf.py

@@ -47,6 +47,7 @@
     'sphinx.ext.intersphinx',
     'sphinx_copybutton',
     'sphinx_togglebutton',
+    'sphinxemoji.sphinxemoji',
     'myst_parser'
 ]
 
@@ -70,7 +71,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -93,7 +94,7 @@
 # documentation.
 #
 html_theme_options = {
-	'navigation_depth': 2,
+
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -164,6 +165,6 @@
 intersphinx_disabled_reftypes = ["*"]
 
 myst_enable_extensions = [
- 'linkify',
- 'colon_fence'
-]
+ 'linkify', 'colon_fence', 'substitution'
+]
+sphinxemoji_style = 'twemoji'

docs/docgen/docgen.py

@@ -16,10 +16,8 @@
 
 def get_files(root): 
     ''' recursively walks every and graps every file name and path '''
-
     lst = os.listdir(root)
-    result = []
-
+    result = [] 
     for name in lst:
       if os.path.isdir(root+os.sep+name):
         if not name in IGNORE_FOLDERS:
@@ -29,53 +27,98 @@ def get_files(root):
       _,ext = os.path.splitext(name)
       if ext.lower() in FILE_EXTENSIONS:
         result.append(root+os.sep+name)
-
     return result
 
-
 def generate_index_rst(TOC):
     ''' 
       Generates the index.rst file 
+
       Builds a table of contents for every seperate folder
     '''
-    index = 'Welcome to %s documentation!\n===============================\n\n' %  (DOCNAME,)
-
-    for dir,value in TOC:
-      # print('Linking: ' + dir)
-      index += '.. toctree::\n   :maxdepth: 2\n\n	:caption: %s\n\n' % (dir.upper().replace(os.sep,' -> '),)
-
+
+    index = "Welcome to |:bee:| %s documentation" %  (DOCNAME,)
+    index += "\n"+ ("="*len(index)) + "\n\n" 
+
+    class rstFile:
+      def __init__(self, r, t):
+        self.Root = r
+        self.Text = t
+
+    fileArr = []
+    index += ".. toctree::\n    :titlesonly:\n"
+
+    for dir,value in TOC:  
+
+      print('Value: ' + str(value))
+      fileName = os.path.splitext(dir)[0].split(os.sep)[0]
+      if fileName == "root":
+        continue
+
+      fileRST = "source/" + fileName + ".rst"
+
+      hasElement = False
+      for f in fileArr:
+        if f.Root == fileRST:
+          hasElement = True
+          break
+
+      fileText = ""
+
+      if not hasElement:
+        fileArr.append(rstFile(fileRST, ""))
+        if fileName != "root":
+          index += "\n    " + fileName
+      else:
+        fileText += "\n\n-----------\n\n"
+
+      if fileName != "root":   
+        fileText += ".. toctree::\n  :maxdepth: 2\n  :caption: %s\n" % (dir.upper().replace(os.sep," -> "),)
+
       for name in value:
-        # print('   * ' + name)
-        index += '   ' + name + '\n' 
-      index += '\n-----------\n\n'
+        fileText += "\n  " + name
+
+
+      for f in fileArr:
+        if f.Root == fileRST:
+          f.Text += fileText
+          break
+
+    for f in fileArr:
+      fileName = os.path.splitext(os.path.basename(f.Root))[-2]
+      mdFile = "source" + os.sep + fileName + ".md"
+      if os.path.exists(mdFile):
+        tmp = open(mdFile, "a")
+        tmp.write("\n" + "```{eval-rst}\n" + f.Text + "\n```")
+      else:
+        tmp = open(f.Root, "w+")
+        title = os.path.splitext(os.path.basename(f.Root).upper())[0]
+        title += "\n" + ("=" * len(title)) + "\n\n"
+        tmp.write(title + f.Text)  
+      tmp.close()
+
+
+    i = open("source/index.rst", "w+")
 
-    i = open('source/index.rst', 'w+')
     i.write(index)
     i.close()
-
-
+
 def generate(root):
     ''' 
       Generates md by walking the specified directly
-    '''
-
+    '''   
     if not os.path.exists('source'):
-        os.mkdir('source')
+      os.mkdir('source')
 
     paths = get_files(root)
     NameToID = {}
-    TOC = []
-
+    TOC = []  
     added = set()
 
     for filename in paths:
-      # print(filename)
-
-      # extract path, directory name, and filename without extension
       path = os.path.dirname(filename)
       dir  = path[len(root)+1:]
       name = os.path.basename(os.path.splitext(filename)[0])
-    
+
       # read in the sourcefile
       with open(filename, 'r') as f:
         contents = f.read()
@@ -86,23 +129,21 @@ def generate(root):
         name = name + '('+dir.replace(os.sep,'_')+')'
       added.add(name)
 
-
       # extract all comments
       res = commentregex.findall(contents)
       if len(res) == 0:
-        print('WARNING: ', name, ' is not documented')
+        print("WARNING: ", name, " is not documented")
         continue
 
       # generate a output file
-      out = open('source/%s.md' % name, 'w+')
-
-      # write the rst-style'd comments to the output file
-      for doc in res:
-        doc = doc[2:][:-2];
-
+      out = open("source/%s.md" % name, "w+")
+      # write the markdown-style'd comments to the output file
+      for comment in res:  
+        doc = comment[2:][:-2];
         out.write(doc)
-        out.write('\n\n')
-        out.write('------------\n')
+        if comment != res[-1]:
+          out.write('\n\n')
+          out.write('- - -\n')
       out.close()
 
       # Table of Contents
@@ -114,14 +155,11 @@ def generate(root):
 
     # finally build the index file
     generate_index_rst(TOC)
-
     os.system('sphinx-build source build -c .')
-	
+
 if __name__ == '__main__':
     generate(sys.argv[1])
-
     if os.path.exists('source'):
         for filename in os.listdir('source'):
-            os.remove('source' + os.sep + filename)
-
-        os.rmdir('source') 
+            os.remove('source' + os.sep + filename)      
+        os.rmdir('source')