Skip to content

Commit

Permalink
docs: Switch from Sphinx to Mkdocs for building documentation.
Browse files Browse the repository at this point in the history
* docs: Switch to using markdown for the readme.
* docs: Use html entity code instead of unicode character.
* docs: Update README.md with the rest of the supported devices.
* docs: Update CSS overrides to move back down to a 2 pixel border in the support table.
* docs: Add $ to console section with pip install command.
* docs: switch to shell code block
* docs: Update legend to have all terms to make tables cleaner.
* docs: Simply reference the glossary on the main page to make it render nicely for GitHub and PyPI.
* docs: Add newline to glossary to make it render better on GitHub.
* docs: Add link to glossary in readme.
* docs: Substitute the links for documentation cross-references when building the documentation.
* docs: Add memory profiling tools to diagnose build issues.
* Switch to using mkdocs for documentation builds (#11)
* docs: Switch to using mkdocs.
* docs: Got basic code syntax highlighting working.
* docs: Override the theme.js file to hide open/close buttons that don't need to be there.
* docs: Added the ability to load in external code files to the docs.
* docs: Updated examples in the basic_usage.md file.
* docs: Update known words.
* docs: Update links to repo.
* docs: Update links to repos and update glossary plugin.
* test: Got doc tests working.
* test: Fixed the linkchecker test.
* docs: Update tox config for docs.
* docs: Start working on API docs.
* docs: Update glossary plugin to use a version that supports unicode characters as glossary entries.
* ci: Add file sorter for known_words.txt.
* ci: Remove unneeded pre-commit hook.
* docs: Add custom template for package files.
* fix: Add missing init file.
* docs: Updated all drivers with init methods to enable docs to build properly.
* docs: Update the auto-generated commands to better render in the documentation.
* docs: Implement a macro that will create mermaid class diagrams.
* refactor: Move a class only used for type hinting into a new module and convert to a private class.
* test: Fix a test based on new file paths.
* docs: Remove unused css file and update links in python docstrings.
* docs: Install the package when building docs to allow diagrams to be created properly.
* docs: Update site path when building docs with tox.
* docs: Update auto-generated python docstrings to render properly.
* ci: Lock docutils version while the bad version is still on PyPI.
* docs: Remove unneeded js files.
* docs: Add links to API in various docs.
* ci: Remove a pre-commit hook that is failing in some CI environments.
* style: Use Python 3.8 syntax for type hinting.
* docs: Update method of including python code snippets to allow mdformat to be used to format markdown files.
* docs: Update config to correctly set the enabled key.
* test: Update doc test config options.
* docs: Ignore directories that start with double underscores.
* docs: Update requirements for documentation so that code highlighting works properly.
* build: Update all dependencies to be locked to major versions to prevent breaking changes from affecting the package.
* ci: Update dependency updater script to lock requirements for testing and docs for repeatable builds.
* docs: Update site URL, badge, and workflow to prep for move to ReadtheDocs.
* docs: Update links.
* fix: Update items found by Pull Request checks.
* fix: Update links in readme for now.
* docs: Update a few docs to render properly and with better linkage to other documentation.
* docs: Update displayed text in some docstring cross-references.
  • Loading branch information
nfelt14 committed May 2, 2024
1 parent 337d199 commit 6d60047
Show file tree
Hide file tree
Showing 1,448 changed files with 1,576,444 additions and 1,620,887 deletions.
1 change: 1 addition & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ updates:
directory: /
schedule:
interval: weekly
versioning-strategy: increase-if-necessary
groups:
python-dependencies:
patterns: ['*']
Expand Down
39 changes: 0 additions & 39 deletions .github/workflows/deploy-documentation.yml

This file was deleted.

7 changes: 0 additions & 7 deletions .github/workflows/test-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,6 @@ jobs:
tox_env: [docs, doctests]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20 # The node version needs to stay in sync with .readthedocs.yml
- name: Install non-python documentation dependencies
run: |
npm install -g @mermaid-js/mermaid-cli
sudo apt install --no-install-recommends --assume-yes graphviz
- name: Set up Python
uses: actions/setup-python@v5
with:
Expand Down
7 changes: 6 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ tm_devices.toml
tm_devices.yaml
tm_devices.yml
*.log
*.dat

# Poetry lock file
poetry.lock
Expand Down Expand Up @@ -60,12 +61,16 @@ tests/samples/generated_stubs/*
tests/verify_devices.yaml
prof/

# Sphinx documentation
# Documentation
.docs*/
docs/_build/
docs/autoapi/
docs/_autoapi/
docs/reference/
_readthedocs/
site*/
.site*/
*.inv

# Jupyter Notebook
.ipynb_checkpoints
Expand Down
48 changes: 27 additions & 21 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -11,21 +11,28 @@ ci:
- pyright
- pyright-verifytypes
- pyroma
- poetry-audit
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.6.0
hooks:
- id: check-yaml
args: [--unsafe]
- id: check-toml
- id: check-json
- id: check-xml
# TODO: figure out why this hook is failing in a few environments
# - id: file-contents-sorter
# files: ^(docs/known_words.txt)$
# args: [--unique, --ignore-case]
- id: requirements-txt-fixer
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-case-conflict
- id: check-merge-conflict
- id: check-added-large-files
args: [--maxkb=3000, --enforce-all]
- id: forbid-new-submodules
- id: forbid-submodules
- id: pretty-format-json
args: [--autofix, --indent=4]
- repo: https://github.com/Lucas-C/pre-commit-hooks
Expand All @@ -41,7 +48,7 @@ repos:
- id: check-github-actions
- id: check-github-workflows
- repo: https://github.com/commitizen-tools/commitizen
rev: v3.24.0
rev: v3.25.0
hooks:
- id: commitizen
stages: [commit-msg]
Expand All @@ -51,6 +58,7 @@ repos:
- id: blacken-docs
files: \.(rst|md|markdown|tex)$
additional_dependencies: [black==23.12.1] # This may need to be updated/removed in the future once ruff supports formatting python code blocks in markdown
args: [--line-length=100]
- repo: https://github.com/lyz-code/yamlfix
rev: 1.16.0
hooks:
Expand All @@ -59,31 +67,21 @@ repos:
rev: 0.7.17
hooks:
- id: mdformat
args: [--number, --end-of-line, keep]
args: [--number, --end-of-line, keep, --ignore-missing-references]
additional_dependencies:
- setuptools # This is required since Python 3.12 no longer installs setuptools by default in virtual environments
- mdformat-myst
- mdformat-toc
- mdformat-frontmatter
- mdformat-beautysh
- mdformat-black
- black==23.12.1 # This may need to be updated/removed in the future once ruff supports formatting python code blocks in markdown
- mdformat-config
- mdformat-footnote
- mdformat-frontmatter
- mdformat-gfm
- mdformat-mkdocs
- mdformat-shfmt
- mdformat-simple-breaks
- mdformat-tables
- mdformat-toc
- mdformat-web
- mdformat-gfm
- mdformat-footnote
# Currently rstcheck doesn't work with the templates
# - repo: https://github.com/rstcheck/rstcheck
# rev: v6.1.2
# hooks:
# - id: rstcheck
# additional_dependencies: [tomli, sphinx]
# TODO: enable this, will require configuration
# - repo: https://github.com/jackdewinter/pymarkdown
# rev: v0.9.11
# hooks:
# - id: pymarkdown
- mdformat-wikilink
- repo: https://gitlab.com/smop/pre-commit-hooks
rev: v1.0.0
hooks:
Expand Down Expand Up @@ -124,6 +122,14 @@ repos:
pass_filenames: false
always_run: true
args: [., --min=10]
- id: poetry-audit
name: poetry-audit
entry: poetry
language: system
types: [toml]
pass_filenames: false
always_run: true
args: [audit, --json]
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.4.2
hooks:
Expand Down
10 changes: 2 additions & 8 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
@@ -1,20 +1,14 @@
---
# Required
version: 2
# Image to use
build:
os: ubuntu-22.04
tools:
python: '3.11' # This needs to stay in sync with pyproject.toml and any CI scripts
nodejs: '20' # This needs to stay in sync with any CI scripts
jobs:
post_install: [npm install -g @mermaid-js/mermaid-cli]
# Configuration
python:
install:
- requirements: docs/requirements.txt
- method: pip
path: .
sphinx:
mkdocs:
configuration: mkdocs.yml
fail_on_warning: true
formats: [pdf]
Loading

0 comments on commit 6d60047

Please sign in to comment.