📝 Bootstrap PyDocs (#171)

* add pydocs

* regenerate pydocs

* add initial pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update pydoc workflow

* update relative path

* fix docstrings

* fix docstrings

* replace double with single back ticks

* fix docstrings and add examples

* fix docstrings and add examples

* remove python from code block

* disable escape html chars

* add python back to code block

* test inline toc

* remove inline toc

* add post-render callback

* add post render callback and template

* remove unneeded md output

* pip install editfrontmatter

* replace .md with .py

* removed pydoc output

* update gitignore

* update pydocs workflow

Author: sserrata

.github/workflows/pydocs.yml

@@ -0,0 +1,86 @@
+name: PyDocs
+
+on:
+  push:
+    branches:
+      - master
+  pull_request_target:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: Generate docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+          architecture: 'x64'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pipx
+          python -m pip install editfrontmatter
+          pipx install 'pydoc-markdown>=4.0.0,<5.0.0'
+
+      - name: Generate markdown docs
+        run: |
+          pydoc-markdown -vv
+
+      - name: Upload markdown artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: docs-dir
+          path: docs/
+
+  pull:
+    name: Open pull request
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout docs repository
+        uses: actions/checkout@v2
+        with:
+          repository: 'PaloAltoNetworks/cortex.pan.dev'
+
+      - name: Download markdown artifacts
+        uses: actions/download-artifact@v2
+        with:
+          name: docs-dir
+          path: docs/
+
+      - name: Commit changes
+        run: |
+          git config --global user.email "sserrata@paloaltonetworks.com"
+          git config --global user.name "Steven Serrata"
+          git add .
+          git commit -m "update pydocs"
+
+      - name: Create Pull Request
+        id: pydocs
+        uses: peter-evans/create-pull-request@v3
+        with:
+          token: ${{ secrets.PYDOC_TOKEN }}
+          commit-message: Update pydocs
+          committer: GitHub <noreply@github.com>
+          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
+          delete-branch: true
+          title: '[PyDocs] Update python library docs'
+          body: |
+            Update pydocs
+            - Docs generated with `pydoc-markdown`
+
+      - name: Check outputs
+        run: |
+          echo "Pull Request Number - ${{ steps.pydocs.outputs.pull-request-number }}"
+          echo "Pull Request URL - ${{ steps.pydocs.outputs.pull-request-url }}"

.gitignore

@@ -69,4 +69,7 @@ target/
 
 # IDE stuff
 .idea/*
-.vscode/*
+.vscode/*
+
+# pydoc-markdown
+docs/**/*.md

docs/post_render.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+
+from editfrontmatter import EditFrontMatter
+import os
+import glob
+
+
+def main():
+    template_str = "".join(open(os.path.abspath("docs/template.j2"), "r").readlines())
+    md_files = glob.glob("./docs/**/*.md", recursive=True)
+    for path in md_files:
+        github_base_url = "https://github.com/PaloAltoNetworks/pan-cortex-data-lake-python/blob/master/pan_cortex_data_lake"
+        github_file_path = path.split("/reference")[1].replace(".md", ".py")
+        custom_edit_url = f"{github_base_url}{github_file_path}"
+        proc = EditFrontMatter(file_path=path, template_str=template_str)
+        proc.run({"custom_edit_url": custom_edit_url})
+        proc.writeFile(path)
+
+
+if __name__ == "__main__":
+    main()

docs/template.j2

@@ -0,0 +1 @@
+custom_edit_url: {{ custom_edit_url }}

pan_cortex_data_lake/adapters/adapter.py

@@ -22,7 +22,7 @@ def fetch_credential(self, credential=None, profile=None):
 
         Args:
             credential (str): Credential to fetch.
-            profile (str): Credentials profile. Defaults to ``'default'``.
+            profile (str): Credentials profile. Defaults to 'default'.
 
         """
         pass
@@ -51,9 +51,9 @@ def write_credentials(self, credentials=None, profile=None, cache_token=None):
         :::
 
         Args:
-            cache_token (bool): If ``True``, stores ``access_token`` in token store. Defaults to ``True``.
+            cache_token (bool): If `True`, stores `access_token` in token store. Defaults to `True`.
             credentials (class): Read-only credentials.
-            profile (str): Credentials profile. Defaults to ``'default'``.
+            profile (str): Credentials profile. Defaults to 'default'.
 
         """
         pass