replace recommonmark with myst_parser (#358)

Author: tora-kozic

CONTRIBUTING.md

@@ -172,7 +172,7 @@ tox -e docs
 To build and run the documentation locally, run the following from the `docs` directory:
 
 ```bash
-pip install sphinx recommonmark sphinx_rtd_theme
+pip install sphinx myst_parser sphinx_rtd_theme
 make html
 ```
 

docs/commands.md

@@ -1,5 +1,25 @@
 # Commands
 
+```{eval-rst}
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+    :glob:
+
+    Alert Rules <commands/alertrules.rst>
+    Alerts <commands/alerts.rst>
+    Audit Logs <commands/auditlogs.rst>
+    Cases <commands/cases.rst>
+    Departing Employee <commands/departingemployee.rst>
+    Devices <commands/devices.rst>
+    High Risk Employee <commands/highriskemployee.rst>
+    Legal Hold <commands/legalhold.rst>
+    Profile <commands/profile.rst>
+    Security Data <commands/securitydata.rst>
+    Trusted Activities <commands/trustedactivities.rst>
+    Users <commands/users.rst>
+```
+
 * [Alert Rules](commands/alertrules.rst)
 * [Alerts](commands/alerts.rst)
 * [Audit Logs](commands/auditlogs.rst)

docs/conf.py

@@ -12,8 +12,6 @@
 import os
 import sys
 
-from recommonmark.transform import AutoStructify
-
 import code42cli.__version__ as meta
 
 # -- Project information -----------------------------------------------------
@@ -40,10 +38,13 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
-    "recommonmark",
+    "myst_parser",
     "sphinx_click",
 ]
 
+# Add myst_parser types to suppress warnings
+suppress_warnings = ["myst.header"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -85,8 +86,15 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
-html_theme_options = {"style_nav_header_background": "#f0f0f0", "logo_only": True}
+
+html_theme_options = {
+    "style_nav_header_background": "#f0f0f0",
+    "logo_only": True,
+    # TOC options
+    "navigation_depth": 4,
+    "titles_only": True,
+    "collapse_navigation": False,
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -111,15 +119,7 @@
 
 
 def setup(app):
-    app.add_config_value(
-        "recommonmark_config",
-        {
-            # 'url_resolver': lambda url: github_doc_root + url,            'auto_toc_tree_maxdepth': 2,
-            "enable_eval_rst": True
-        },
-        True,
-    )
-    app.add_transform(AutoStructify)
+    pass
 
 
 sys.path.insert(0, os.path.abspath(".."))

docs/guides.md

@@ -1,14 +1,34 @@
 # User Guides
 
+```{eval-rst}
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+    :glob:
+
+    Get started with the Code42 command-line interface (CLI) <userguides/gettingstarted.md>
+    Configure a profile <userguides/profile.md>
+    Ingest data into a SIEM <userguides/siemexample.md>
+    Manage detection list users <userguides/detectionlists.md>
+    Manage legal hold users <userguides/legalhold.md>
+    Clean up your environment by deactivating devices <userguides/deactivatedevices.md>
+    Write custom extension scripts using the Code42 CLI and Py42 <userguides/extensions.md>
+    Manage users <userguides/users.md>
+    Configure trusted activities <userguides/trustedactivities.md>
+    Configure alert rules <userguides/alertrules.md>
+    Add and manage cases <userguides/cases.md>
+    Perform bulk actions <userguides/bulkcommands.md>
+```
+
 * [Get started with the Code42 command-line interface (CLI)](userguides/gettingstarted.md)
 * [Configure a profile](userguides/profile.md)
-* [Ingest Data into a SIEM](userguides/siemexample.md)
+* [Ingest data into a SIEM](userguides/siemexample.md)
 * [Manage detection list users](userguides/detectionlists.md)
 * [Manage legal hold users](userguides/legalhold.md)
 * [Clean up your environment by deactivating devices](userguides/deactivatedevices.md)
-* [Write custom extension scripts using the Code42 CLI and py42](userguides/extensions.md)
-* [Manage Users](userguides/users.md)
-* [Configure Trusted Activities](userguides/trustedactivities.md)
-* [Configure Alert Rules](userguides/alertrules.md)
-* [Add and Manage Cases](userguides/cases.md)
-* [Use Bulk Commands](userguides/bulkcommands.md)
+* [Write custom extension scripts using the Code42 CLI and Py42](userguides/extensions.md)
+* [Manage users](userguides/users.md)
+* [Configure trusted activities](userguides/trustedactivities.md)
+* [Configure alert rules](userguides/alertrules.md)
+* [Add and manage cases](userguides/cases.md)
+* [Perform bulk actions](userguides/bulkcommands.md)

docs/index.md

@@ -1,5 +1,21 @@
 # Code42 command-line interface (CLI)
 
+```{eval-rst}
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+
+    guides
+```
+
+```{eval-rst}
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+
+    commands
+```
+
 [![license](https://img.shields.io/pypi/l/code42cli.svg)](https://pypi.org/project/code42cli/)
 [![versions](https://img.shields.io/pypi/pyversions/code42cli.svg)](https://pypi.org/project/code42cli/)
 

docs/userguides/gettingstarted.md

@@ -68,7 +68,7 @@ python3 -m pip install code42cli --upgrade
 
 ## Authentication
 
-```eval_rst
+```{eval-rst}
 .. important:: The Code42 CLI currently only supports token-based authentication.
 ```
 

docs/userguides/siemexample.md

@@ -174,7 +174,7 @@ The following tables map the file event data from the Code42 CLI to common event
 The table below maps JSON fields, CEF fields, and [Forensic Search fields](https://code42.com/r/support/forensic-search-fields)
 to one another.
 
-```eval_rst
+```{eval-rst}
 
 +----------------------------+---------------------------------+----------------------------------------+
 | JSON field                 | CEF field                       | Forensic Search field                  |
@@ -255,7 +255,7 @@ to one another.
 
 See the table below to map file events to CEF signature IDs.
 
-```eval_rst
+```{eval-rst}
 
 +--------------------+-----------+
 | Exfiltration event | CEF field |

docs/userguides/trustedactivities.md

@@ -49,7 +49,7 @@ To update multiple trusted activities at once, enter information about the trust
 code42 trusted-activities bulk update update_trusted_activities.csv
 ```
 
-```eval_rst
+```{eval-rst}
 .. note::
     The ``bulk update`` command cannot be used to clear the description of a trusted activity because you cannot indicate an empty string in a CSV format.
     Pass an empty string to the ``description`` option of the ``update`` command to clear the description of a trusted activity.

tox.ini

@@ -24,9 +24,9 @@ commands =
 
 [testenv:docs]
 deps =
-    sphinx
-    recommonmark
-    sphinx_rtd_theme
+    sphinx == 4.4.0
+    myst_parser == 0.16
+    sphinx_rtd_theme == 0.5.2
     sphinx-click
 whitelist_externals = bash