doc: Implement mkdoc to expose eos-downloader documentation (#109)

* doc: Implement mkdoc to expose eos-downloader documentation

* ci: Add doc autobuild

* test(pytest): Fix module rename

.github/workflows/main_doc.yml

@@ -0,0 +1,37 @@
+---
+# This is deploying the latest commits on main to main documentation
+name: Mkdocs
+on:
+  push:
+    branches:
+      - main
+    paths:
+      # Run only if any of the following paths are changed when pushing to main
+      - "docs/**"
+      - "mkdocs.yml"
+      - "eos_downloader/**"
+  workflow_dispatch:
+
+jobs:
+  'build_latest_doc':
+    name: 'Update Public main documentation'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: 'Setup Python 3 on runner'
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Setup Git config
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+
+      - name: 'Build mkdocs content and deploy to gh-pages to main'
+        run: |
+            pip install .[doc]
+            mike deploy --push main

.github/workflows/release.yml

@@ -114,3 +114,25 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
 
+
+  release-doc:
+    name: "Publish documentation for release ${{github.ref_name}}"
+    runs-on: ubuntu-latest
+    needs: [docker-in-docker]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: 'Setup Python 3 on runner'
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Setup Git config
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+
+      - name: 'Build mkdocs content to site folder'
+        run: |
+          pip install .[doc]
+          mike deploy --update-alias --push  ${{github.ref_name}} stable

docs/README.md

@@ -0,0 +1,43 @@
+<!-- [![tests](https://github.com/titom73/eos-downloader/actions/workflows/pr-management.yml/badge.svg?event=push)](https://github.com/titom73/eos-downloader/actions/workflows/pr-management.yml)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/eos-downloader)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)
+![GitHub release](https://img.shields.io/github/v/release/titom73/arista-downloader)
+![PyPI - Downloads/month](https://img.shields.io/pypi/dm/eos-downloader)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit) -->
+
+# Arista Software Downloader
+
+A project to download Arista softwares to local folder, Cloudvision or EVE-NG. It comes in 2 way: a framework with object to automate Arista software download and a CLI for human activities.
+
+> [!CAUTION]
+> This script should not be deployed on EOS device. If you do that, there is no support to expect from Arista TAC team.
+
+```bash
+# install eos-downloader from pypi
+pip install eos-downloader
+
+# download EOS swi for EOS 64bits
+ardl --token <your-token> get eos --format 64 --latest --release-type M
+```
+
+> [!NOTE]
+> The main branch is not the stable branch and can be broken between releases. It is safe to consider using tags for stable versions. All versions on pypi servers are considered stable.
+
+## FAQ
+
+On EVE-NG, you may have to install/upgrade __pyOpenSSL__ in version `23.0.0`:
+
+```bash
+# Error when running ardl: AttributeError: module 'lib' has no attribute 'X509_V_FLAG_CB_ISSUER_CHECK'
+
+$ pip install pyopenssl --upgrade
+```
+
+## Author
+
+From an original idea of [@Mark Rayson](https://github.com/Sparky-python) in [arista-netdevops-community/eos-scripts](https://github.com/arista-netdevops-community/eos-scripts)
+
+## License
+
+Code is under [Apache2](LICENSE) License

docs/api/helpers.md

@@ -0,0 +1 @@
+## ::: eos_downloader.helpers

docs/api/logics/arista_server.md

@@ -0,0 +1 @@
+## ::: eos_downloader.logics.arista_server

docs/api/logics/arista_xml_server.md

@@ -0,0 +1 @@
+## ::: eos_downloader.logics.arista_xml_server

docs/api/logics/download.md

@@ -0,0 +1 @@
+## ::: eos_downloader.logics.download

docs/api/models/custom_types.md

@@ -0,0 +1 @@
+## ::: eos_downloader.models.types

docs/api/models/data.md

@@ -0,0 +1,3 @@
+## ::: eos_downloader.models.data.software_mapping
+
+## ::: eos_downloader.models.data

docs/api/models/version.md

@@ -0,0 +1 @@
+## ::: eos_downloader.models.version

docs/stylesheets/extra.material.css

@@ -0,0 +1,245 @@
+[data-md-color-scheme="slate"] {
+  --md-hue: 210;
+}
+
+#page {
+  counter-reset: heading;
+}
+
+:root {
+  /* Color schema based on Arista Color Schema */
+  /* Default color shades */
+  --md-default-fg-color:               #000000;
+  --md-default-fg-color--light:        #444343;
+  --md-default-fg-color--lighter:      #FFFFFF;
+  --md-default-fg-color--lightest:     #FFFFFF;
+  --md-default-bg-color:               #FFFFFF;
+  --md-default-bg-color--light:        #FFFFFF;
+  --md-default-bg-color--lighter:      #FFFFFF;
+  --md-default-bg-color--lightest:     #FFFFFF;
+
+  /* Primary color shades */
+  --md-primary-fg-color:               #27569B;
+  --md-primary-fg-color--light:        #FFFFFF;
+  --md-primary-fg-color--dark:         #27569B;
+  --md-primary-bg-color:               #FFFFFF;
+  --md-primary-bg-color--light:        #FFFFFF;
+
+  /* Accent color shades */
+  --md-accent-fg-color:                #27569B;
+  --md-accent-bg-color:                #27569B;
+  --md-accent-bg-color--light:         #27569B;
+
+  /* Link color */
+  --md-typeset-a-color:                #27569B;
+  --md-typeset-a-color-fg:             #FFFFFF;
+  --md-typeset-a-color-bg:             #27569B;
+
+  /* Code block color shades */
+  --md-code-bg-color:                  #E6E6E6;
+  --md-code-border-color:              #0000004f;
+  --block-code-bg-color:               #e4e4e4;
+
+  font-size: 1.1rem;
+  font-feature-settings: "kern","liga";
+  font-family: var(--md-text-font-family,_),-apple-system,BlinkMacSystemFont,Helvetica,Arial,sans-serif;
+  -webkit-font-smoothing: antialiased;
+
+}
+
+[data-md-color-scheme="slate"] {
+
+  /* Default color shades */
+  --md-default-fg-color--light: #949393;
+
+  /* Link color */
+  --md-typeset-a-color:                #75aaf8;
+  --md-typeset-a-color-fg:             #FFFFFF;
+  --md-typeset-a-color-bg:             #27569B;
+
+  /* Code block color shades */
+  --md-code-border-color:              #aec6db4f;
+}
+
+.md-banner {
+  background-color: #f5c842;
+  color: #000000;
+
+}
+
+@media only screen and (min-width: 76.25em) {
+  .md-main__inner, .md-header__inner {
+    max-width: 85%;
+  }
+  .md-sidebar--primary {
+    left: 5%;
+  }
+  .md-sidebar--secondary {
+    right: 5%;
+    margin-left: 0;
+    -webkit-transform: none;
+    transform: none;
+  }
+}
+
+@media only screen {
+
+  .md-typeset a:hover {
+    background-color: var(--md-typeset-a-color-bg);
+    color: var(--md-typeset-a-color-fg);
+  }
+  .md-footer-nav {
+      background-color: var(--md-default-bg-color--light);
+      color: var(--md-accent-fg-color--transparent)
+  }
+  .md-footer {
+    height: 2%;
+  }
+  .md-footer-nav__direction {
+    position: absolute;
+    right: 0;
+    left: 0;
+    margin-top: -1rem;
+    padding: 0 1rem;
+    color: var(--md-default-fg-color--light);
+    font-size: .64rem;
+  }
+  .md-footer-nav__title {
+    font-size: 1.2rem;
+    line-height: 10rem;
+    color: var(--md-default-fg-color--light);
+  }
+
+  .md-typeset h2 {
+    line-height: 2em;
+    font-size: 1.5rem;
+    margin: 1em 0;
+    /* font-weight: 700; */
+    letter-spacing: -.01em;
+    color: var(--md-default-fg-color--light);
+    text-transform: capitalize;
+    font-style: normal;
+    font-weight: bolder;
+  }
+
+  .md-typeset h3 {
+    line-height: 1em;
+    font-size: 1.3rem;
+    margin: 1em 0;
+    letter-spacing: -.01em;
+    color: var(--md-default-fg-color--light);
+    font-style: normal;
+    font-weight: bold;
+  }
+
+  .md-typeset h4 {
+    font-size: 1.1rem;
+    margin: 1em 0;
+    font-weight: 700;
+    letter-spacing: -.01em;
+    line-height: 1em;
+    color: var(--md-default-fg-color--light);
+    font-style: italic;
+  }
+
+  .md-typeset h5,
+  .md-typeset h6 {
+    font-size: 0.9rem;
+    margin: 1em 0;
+    letter-spacing: -.01em;
+    color: var(--md-default-fg-color--light);
+    font-style: italic;
+  }
+
+  .md-typeset table:not([class]) th {
+    min-width: 5rem;
+    padding: .6rem .8rem;
+    color: var(--md-default-fg-color);
+    vertical-align: top;
+    text-align: left;
+  }
+  .md-typeset table:not([class]) td {
+    /* padding: .9375em 1.25em; */
+    border-collapse: collapse;
+    vertical-align: center;
+    text-align: left;
+  }
+  .md-typeset code {
+    padding: 0 .2941176471em;
+    font-size: 100%;
+    word-break: break-word;
+    background-color: var(--md-code-bg-color);
+    border-radius: .1rem;
+    -webkit-box-decoration-break: clone;
+    box-decoration-break: clone;
+  }
+  .highlight code {
+    background-color: var(--md-code-bg-color);
+    font-size: 90%;
+    border-radius: 0%;
+  }
+  .md-typeset .admonition, .md-typeset details {
+      margin: 1.5625em 0;
+      padding: 0 .6rem;
+      overflow: hidden;
+      font-size: 90%;
+      page-break-inside: avoid;
+      border-left: .2rem solid var(--md-accent-bg-color);
+      border-left-color: var(--md-accent-bg-color);
+      border-radius: .1rem;
+      box-shadow: 0 .2rem .5rem rgba(0,0,0,.05),0 0 .05rem rgba(0,0,0,.1);
+  }
+  /* .md-typeset .note > .admonition-title, .md-typeset .note > summary {
+    background-color: var(--md-accent-bg-color);
+    color: var(--md-default-fg-color--lighter)
+  } */
+  .md-typeset__table {
+    min-width: 80%;
+  }
+  .md-typeset table:not([class]) {
+      display: table;
+  }
+
+  .mdx-content__footer {
+      margin-top: 20px;
+      text-align: center;
+  }
+  .mdx-content__footer a {
+      display: inline-block;
+      transition: transform 250ms cubic-bezier(0.1, 0.7, 0.1, 1), color 125ms;
+  }
+  .mdx-content__footer a:focus, .mdx-content__footer a:hover {
+      transform: scale(1.2);
+  }
+
+  .md-typeset table:not([class]) th {
+      min-width: 5rem;
+      padding: .6rem .8rem;
+  }
+
+  .md-footer-copyright {
+      color: var(--md-footer-fg-color--lighter);
+      font-size: .64rem;
+      margin: auto 0.6rem;
+      padding: 0.4rem;
+      width: 100%;
+      text-align: center;
+  }
+  .img_center {
+    display: block;
+    margin-left: auto;
+    margin-right: auto;
+    border-radius: 1%;
+  }
+}
+
+/* mkdocstrings css from official repo to indent sub-elements nicely */
+/* Indentation. */
+div.doc-contents {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
+h5.doc-heading {
+  /* Avoid to capitalize h5 headers for mkdocstrings */
+  text-transform: none;
+}

docs/stylesheets/highlight.js

@@ -0,0 +1,3 @@
+document$.subscribe(() => {
+  hljs.highlightAll()
+})

docs/stylesheets/tables.js

@@ -0,0 +1,6 @@
+document$.subscribe(function() {
+  var tables = document.querySelectorAll("article table")
+  tables.forEach(function(table) {
+    new Tablesort(table)
+  })
+})