fix mkdocstrings usage/reqs (#70)

* fix mkdocstrings usage/reqs
   - removed some unnecessary CSS
* check mkdocs builds on all branches
   - only publish from master

Author: 2bndy5

.github/workflows/mkdocs-deploy.yml

@@ -2,7 +2,6 @@ name: MkDocs Deploy
 
 on:
   push:
-    branches: [master]
   workflow_dispatch:
 
 jobs:
@@ -15,7 +14,11 @@ jobs:
           python-version: 3.x
       - name: Install python action for doc extraction
         run: pip install . -r docs/requirements.txt
+      - name: check mkdocs build
+        if: github.ref != 'refs/heads/master'
+        run: mkdocs build
       - name: Build docs and deploy to gh-pages
+        if: github.ref == 'refs/heads/master'
         run: |
           git config user.name 'github-actions'
           git config user.email '41898282+github-actions[bot]@users.noreply.github.com'

cpp_linter/clang_format_xml.py

@@ -118,7 +118,7 @@ def log_command(self, style: str) -> str:
 
 def parse_format_replacements_xml(src_filename: str):
     """Parse XML output of replacements from clang-format. Output is saved to
-    [`format_advice`][cpp_linter.__init__.GlobalParser.format_advice].
+    [`format_advice`][cpp_linter.GlobalParser.format_advice].
 
     Args:
         src_filename: The source file's name for which the contents of the xml
@@ -146,7 +146,7 @@ def parse_format_replacements_xml(src_filename: str):
 
 def print_fixits():
     """Print all [`XMLFixit`][cpp_linter.clang_format_xml.XMLFixit] objects in
-    [`format_advice`][cpp_linter.__init__.GlobalParser.format_advice]."""
+    [`format_advice`][cpp_linter.GlobalParser.format_advice]."""
     for fixit in GlobalParser.format_advice:
         print(repr(fixit))
         for line_fix in fixit.replaced_lines:

cpp_linter/clang_tidy.py

@@ -102,7 +102,7 @@ def parse_tidy_output() -> None:
 def print_fixits():
     """Print out all clang-tidy notifications from stdout (which are saved to
     clang_tidy_report.txt and allocated to
-    [`tidy_notes`][cpp_linter.__init__.GlobalParser.tidy_notes]."""
+    [`tidy_notes`][cpp_linter.GlobalParser.tidy_notes]."""
     for notification in GlobalParser.tidy_notes:
         print("found", len(GlobalParser.tidy_notes), "tidy_notes")
         print(repr(notification))

cpp_linter/clang_tidy_yml.py

@@ -99,7 +99,7 @@ def __repr__(self) -> str:
 
 def parse_tidy_suggestions_yml():
     """Read a YAML file from clang-tidy and create a list of suggestions from it.
-    Output is saved to [`tidy_advice`][cpp_linter.__init__.GlobalParser.tidy_advice].
+    Output is saved to [`tidy_advice`][cpp_linter.GlobalParser.tidy_advice].
     """
     yml = {}
     with open("clang_tidy_output.yml", "r", encoding="utf-8") as yml_file:
@@ -130,7 +130,7 @@ def parse_tidy_suggestions_yml():
 
 def print_fixits():
     """Print all [`YMLFixit`][cpp_linter.clang_tidy_yml.YMLFixit] objects in
-    [`tidy_advice`][cpp_linter.__init__.GlobalParser.tidy_advice]."""
+    [`tidy_advice`][cpp_linter.GlobalParser.tidy_advice]."""
     for fix in GlobalParser.tidy_advice:
         for diag in fix.diagnostics:
             print(repr(diag))

cpp_linter/run.py

@@ -214,7 +214,7 @@ def is_file_in_list(paths: list, file_name: str, prompt: str) -> bool:
 
 def get_list_of_changed_files() -> None:
     """Fetch the JSON payload of the event's changed files. Sets the
-    [`FILES`][cpp_linter.__init__.Globals.FILES] attribute."""
+    [`FILES`][cpp_linter.Globals.FILES] attribute."""
     start_log_group("Get list of specified source files")
     files_link = f"{GITHUB_API_URL}/repos/{GITHUB_REPOSITORY}/"
     if GITHUB_EVENT_NAME == "pull_request":
@@ -232,7 +232,7 @@ def filter_out_non_source_files(
     ext_list: list, ignored: list, not_ignored: list, lines_changed_only: bool
 ) -> bool:
     """Exclude undesired files (specified by user input 'extensions'). This filter
-    applies to the event's [`FILES`][cpp_linter.__init__.Globals.FILES] attribute.
+    applies to the event's [`FILES`][cpp_linter.Globals.FILES] attribute.
 
     Args:
         ext_list: A list of file extensions that are to be examined.
@@ -327,7 +327,7 @@ def verify_files_are_present() -> None:
 
 def list_source_files(ext_list: list, ignored_paths: list, not_ignored: list) -> bool:
     """Make a list of source files to be checked. The resulting list is stored in
-    [`FILES`][cpp_linter.__init__.Globals.FILES].
+    [`FILES`][cpp_linter.Globals.FILES].
 
     Args:
         ext_list: A list of file extensions that should by attended.
@@ -495,7 +495,7 @@ def capture_clang_tools_output(
     repo_root: str,
 ):
     """Execute and capture all output from clang-tidy and clang-format. This aggregates
-    results in the [`OUTPUT`][cpp_linter.__init__.Globals.OUTPUT].
+    results in the [`OUTPUT`][cpp_linter.Globals.OUTPUT].
 
     Args:
         version: The version of clang-tidy to run.
@@ -733,7 +733,7 @@ def make_annotations(style: str, file_annotations: bool) -> bool:
     return ret_val
 
 
-def parse_ignore_option(paths: str):
+def parse_ignore_option(paths: str) -> tuple:
     """Parse a given string of paths (separated by a '|') into `ignored` and
     `not_ignored` lists of strings.
 

docs/API Reference/cpp_linter.md

@@ -1,3 +1,3 @@
 # Base module
 
-::: cpp_linter.__init__
+::: cpp_linter

docs/requirements.txt

@@ -1,5 +1,5 @@
 mkdocs
-mkdocstrings
+mkdocstrings[python]
 mkdocs-material
 mkdocs-autorefs
 mkdocs-include-markdown-plugin

docs/stylesheets/extra.css

@@ -14,46 +14,5 @@ tr:hover {
 }
 
 th {
-    background-color: var(--md-primary-fg-color--light);
-}
-
-.md-typeset table:not([class]) {
-    /* border-radius: .1rem; */
-    border-radius: 0 1rem 1rem 0;
-    border-left: .2rem solid;
-    border-left-color: var(--md-default-fg-color);
-}
-
-.md-typeset details:not([open])>summary {
-    /* border-radius: .1rem; */
-    border-radius: 0 1rem 1rem 0;
-}
-
-.md-typeset summary {
-    border-top-right-radius: 1rem;
-}
-
-.md-typeset .admonition,
-.md-typeset details {
-    /* border-top-right-radius: .1rem; */
-    border-top-right-radius: 1rem;
-    border-bottom-right-radius: 1rem;
-}
-
-.md-typeset .cite>.admonition-title,
-.md-typeset .cite>summary,
-.md-typeset .quote>.admonition-title,
-.md-typeset .quote>summary {
-    /* background-color: hsla(0,0%,62%,.1); */
-    /* border-color: #9e9e9e; */
-    background-color: hsla(27.9, 68.9%, 41.6%, 0.33);
-    border-color: hsl(27.9, 68.9%, 41.6%);
-}
-
-.md-typeset .admonition.cite,
-.md-typeset .admonition.quote,
-.md-typeset details.cite,
-.md-typeset details.quote {
-    /* border-color: #9e9e9e; */
-    border-color: hsla(27.9, 68.9%, 41.6%);
+    background-color: var(--md-default-fg-color--lightest);
 }

mkdocs.yml

@@ -6,13 +6,13 @@ edit_uri: "blob/master/docs/"
 repo_name: "cpp-linter/cpp-linter-action"
 nav:
   - index.md
-  - "Dev Docs":
-    - API Reference/cpp_linter.md
-    - API Reference/cpp_linter.run.md
-    - API Reference/cpp_linter.clang_tidy.md
-    - API Reference/cpp_linter.clang_tidy_yml.md
-    - API Reference/cpp_linter.clang_format_xml.md
-    - API Reference/cpp_linter.thread_comments.md
+  - 'Dev Docs':
+    - 'API Reference/cpp_linter.md'
+    - 'API Reference/cpp_linter.run.md'
+    - 'API Reference/cpp_linter.clang_tidy.md'
+    - 'API Reference/cpp_linter.clang_tidy_yml.md'
+    - 'API Reference/cpp_linter.clang_format_xml.md'
+    - 'API Reference/cpp_linter.thread_comments.md'
 
 theme:
   name: material