From 26efa0891b491b9b032b166f95b10944729030f3 Mon Sep 17 00:00:00 2001 From: Sara Batllori Date: Fri, 23 Aug 2024 14:13:15 -0700 Subject: [PATCH] Add improvements to sphinx and fix some issues Signed-off-by: Sara Batllori --- docs/_remove/remove_files.txt | 1 + docs/create_manual.py | 36 ++++++++----------- docs/sphinx/_mock/mock_imports.txt | 2 +- docs/sphinx/_scripts/removeStrRst.py | 33 +++++++++-------- docs/sphinx/conf.py | 2 +- .../sphinx/contribution/code-style-python.rst | 2 +- .../sphinx/development/Platform-Detection.rst | 2 +- .../development/Sample-Util-Command.rst | 4 +-- 8 files changed, 39 insertions(+), 43 deletions(-) create mode 100644 docs/_remove/remove_files.txt diff --git a/docs/_remove/remove_files.txt b/docs/_remove/remove_files.txt new file mode 100644 index 0000000000..a2c97654cb --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/create_manual.py b/docs/create_manual.py index 21a892724a..5dc01c42d5 100644 --- 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 index 8433801642..a0384ba254 100644 --- 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 \ No newline at end of file +efi,common,itpii,fcntl,resource,chipsec_tools,chipsec.chipset,edk2,chipsec.config,brotli,EfiCompressor,winerror,win32service,win32service,win32api,win32process,win32security,win32serviceutil,win32file,win32 \ No newline at end of file diff --git a/docs/sphinx/_scripts/removeStrRst.py b/docs/sphinx/_scripts/removeStrRst.py index b4e36fd6c2..53163280cd 100644 --- 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('') - 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('') + 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 index d1eab94b5e..8e87d6f6bb 100644 --- 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 index cb5b830f82..8f9c8beb5e 100644 --- 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/development/Platform-Detection.rst b/docs/sphinx/development/Platform-Detection.rst index dd858b3031..dd42567e90 100644 --- 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 index 02e442c660..a3075307c8 100644 --- 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