Add improvements to sphinx and fix some issues

Signed-off-by: Sara Batllori <[email protected]>
Sae86 · Aug 23, 2024 · c23a673 · c23a673
1 parent ecd50ae
commit c23a673
Show file tree

Hide file tree

Showing 9 changed files with 40 additions and 44 deletions.
diff --git a/docs/_remove/remove_files.txt b/docs/_remove/remove_files.txt
@@ -0,0 +1 @@
+setup.rst,chipsec.rst,chipsec.cfg.rst,chipsec.cfg.parsers.rst,chipsec.cfg.parsers.core_parsers.rst,chipsec.chipset.rst,chipsec.command.rst,chipsec.config.rst,chipsec.library.rst,chipsec.library.architecture.rst,chipsec.library.banner.rst,chipsec.library.bits.rst,chipsec.library.control.rst,chipsec.library.defines.rst,chipsec.library.device.rst,chipsec.library.exceptions.rst,chipsec.library.file.rst,chipsec.library.lock.rst,chipsec.library.logger.rst,chipsec.library.memory.rst,chipsec.library.module_helper.rst,chipsec.library.options.rst,chipsec.library.register.rst,chipsec.library.result_deltas.rst,chipsec.library.returncode.rst,chipsec.library.strings.rst,chipsec.library.structs.rst,chipsec.library.types.rst,chipsec.library.url.rst,chipsec.module.rst,chipsec.module_common.rst,chipsec.parsers.rst,chipsec_main.rst,chipsec_util.rst
diff --git a/docs/create_manual.py b/docs/create_manual.py
@@ -50,22 +50,6 @@
 SPHINX_SCRIPTS_DIR = os.path.join(SPHINX_DIR, '_scripts')
 CHIPSEC_DIR = os.path.normpath(DOCS_DIR + os.sep + os.pardir)
 
-NotWantedFilesList = [
-    'setup.rst',
-    'chipsec.rst',
-    'chipsec.library.banner.rst',
-    'chipsec.cfg.rst',
-    'chipsec.chipset.rst',
-    'chipsec.command.rst',
-    'chipsec.library.defines.rst',
-    'chipsec.library.file.rst',
-    'chipsec.library.logger.rst',
-    'chipsec.module.rst',
-    'chipsec.module_common.rst',
-    'chipsec.library.result_deltas.rst',
-    'chipsec_main.rst',
-    'chipsec_util.rst']
-
 def RunAutoDoc() -> None:
     try:
         os.system(f'sphinx-apidoc -e -f -T -d 10 -o modules {CHIPSEC_DIR} {os.path.join(CHIPSEC_DIR, "*test*")} {os.path.join(CHIPSEC_DIR, "*exceptions*")} {os.path.join(CHIPSEC_DIR, "*tool*")}')
@@ -74,12 +58,20 @@ def RunAutoDoc() -> None:
         raise
 
 def CleanupFilesNotWantedInDoc() -> None:
-    for file in NotWantedFilesList:
-        try:
-            os.remove(os.path.join(SPHINX_MOD_DIR, file))
-        except Exception:
-            print(f'Unable to remove {file}')
-            raise
+    NotWantedFilesList = []
+    list_path = os.path.join(os.path.dirname(__file__), '_remove')
+    for file in os.listdir(list_path):
+        with open(os.path.join(list_path, file), 'r') as f:
+            NotWantedFilesList = f.read()
+        for file in NotWantedFilesList.split(','):
+            RemoveFile(file)
+
+def RemoveFile(file):
+    try:
+        os.remove(os.path.join(SPHINX_MOD_DIR, file))
+    except Exception:
+        print(f'\t\tUnable to remove {file}!!!')
+        pass
 
 def RunScripts() -> None:
     for script in os.listdir(os.path.join(SPHINX_SCRIPTS_DIR)):

diff --git a/docs/sphinx/_mock/mock_imports.txt b/docs/sphinx/_mock/mock_imports.txt
@@ -1 +1 @@
-efi,common,itpii,fcntl,resource,chipsec_tools,chipsec.chipset,edk2
+efi,common,itpii,fcntl,resource,chipsec_tools,chipsec.chipset,edk2,chipsec.config,brotli,EfiCompressor,winerror,win32service,win32service,win32api,win32process,win32security,win32serviceutil,win32file,win32
diff --git a/docs/sphinx/_scripts/removeStrRst.py b/docs/sphinx/_scripts/removeStrRst.py
@@ -45,23 +45,26 @@ def modulesRst():
 
 # Create rst for xml files
 def xmlRst():
+    moduleStr = ''
     for _, _, cfgFiles in os.walk(os.path.join(src_path, 'chipsec', 'cfg', '8086')):
-        moduleStr = ''
         for cfg in cfgFiles:
-            if ".py" not in cfg:
-                moduleStr += '\tchipsec.cfg.8086.{0}.rst\n'.format(cfg)
-
-                with open(os.path.join(src_path, 'chipsec', 'cfg', '8086', cfg), 'r') as f:
-                    xmlContent = f.read()
-
-                commentBegins = xmlContent.find('<!--')
-                commentEnds = xmlContent.find('-->')
-                xmlComment = xmlContent[commentBegins+4:commentEnds] + '\n'
-
-                with open(os.path.join(doc_path, 'modules', 'chipsec.cfg.8086.' + cfg + '.rst'), 'w') as f:
-                    path = "chipsec\\\\cfg\\\\8086\\\\" + cfg
-                    f.write( cfg[:-4] + "\n" + "=" *len(cfg) + "\n\n" + "Path: " + path + "\n\n" + xmlComment )
-
+            if ".py" not in cfg: 
+                try:
+                    with open(os.path.join(src_path, 'chipsec', 'cfg', '8086', cfg), 'r') as f:
+                        xmlContent = f.read()
+                except Exception:
+                    print(f'\t\tUnable to remove {cfg}!!!')
+                    pass
+                else:
+                    moduleStr += '\tchipsec.cfg.8086.{0}.rst\n'.format(cfg)
+                    commentBegins = xmlContent.find('<!--')
+                    commentEnds = xmlContent.find('-->')
+                    xmlComment = xmlContent[commentBegins+4:commentEnds] + '\n'
+
+                    with open(os.path.join(doc_path, 'modules', 'chipsec.cfg.8086.' + cfg + '.rst'), 'w') as f:
+                        path = "chipsec\\\\cfg\\\\8086\\\\" + cfg
+                        f.write( cfg[:-4] + "\n" + "=" *len(cfg) + "\n\n" + "Path: " + path + "\n\n" + xmlComment )
+
         with open(os.path.join(doc_path, 'modules', 'chipsec.cfg.8086.rst'), 'w') as f:
             f.write(".. toctree::\n\n" + moduleStr)
 

diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py
@@ -81,7 +81,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'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

diff --git a/docs/sphinx/contribution/code-style-python.rst b/docs/sphinx/contribution/code-style-python.rst
@@ -78,7 +78,7 @@ If in doubt, follow the existing code style and formatting.
         # Good
         import sys
         from chipsec.module_common import BaseModule
-from chipsec.library.returncode import ModuleResult
+        from chipsec.library.returncode import ModuleResult
 
         # Bad - using '*' and importing sys after local imports
         import *

diff --git a/docs/sphinx/contribution/sphinx.rst b/docs/sphinx/contribution/sphinx.rst
@@ -3,7 +3,7 @@
 Sphinx Version
 ==============
 
-The versions of Sphinx that can be utilized to generate CHIPSEC's documentation are 4.X.X, 5.X.X and 6.X.X.
+The versions of Sphinx that can be utilized to generate CHIPSEC's documentation are 6.X.X, 7.X.X and 8.X.X.
 
 
 Generating Documentation

diff --git a/docs/sphinx/development/Platform-Detection.rst b/docs/sphinx/development/Platform-Detection.rst
@@ -10,7 +10,7 @@ Processor: 0:0.0
 
 PCH: Scans enumerated PCI Devices for corresponding VID/DID per configurations. 
 
-Chip information located in ``chipsec/chipset.py``.
+Chip information located in ``chipsec/chipset.py``
 --------------------------------------------------
 
 Currently requires VID of 0x8086 (Intel) or 0x1022 (AMD).

diff --git a/docs/sphinx/development/Sample-Util-Command.rst b/docs/sphinx/development/Sample-Util-Command.rst
@@ -1,5 +1,5 @@
- Util Command
-===================
+Util Command
+============
 
 .. code-block:: python