pdoc
pre-commit-hooks
pdoc | pre-commit-hooks | |
---|---|---|
10 | 22 | |
1,815 | 4,889 | |
1.4% | 2.1% | |
8.2 | 7.4 | |
1 day ago | 3 days ago | |
Python | Python | |
The Unlicense | MIT License |
Stars - the number of stars that a project has on GitHub. Growth - month over month growth in stars.
Activity is a relative number indicating how actively a project is being developed. Recent commits have higher weight than older ones.
For example, an activity of 9.0 indicates that a project is amongst the top 10% of the most actively developed projects that we are tracking.
pdoc
-
How to Write Impeccably Clean Code That Will Save Your Sanity
You can also use doc-strings to generate automated documentation for your code using a library like pdoc. Consider the following example from Stack-Scraper and the corresponding documentation generated using pdoc library.
-
what's a good documentation platform that you guys would recommend?
I’ve used sphinx extensively and though it is one of the standards and does a ton, I do not like or recommend it. Personally, I realllly like pdoc for its simplicity. Do not confused pdoc with pdoc3
-
The Slow March of Progress in Programming Language Tooling
RE browser vs reading the code: sounds like you have a nicer setup than my neovim setup. Although I think my first point still holds unless CLion handles that case too.
With respect to the rest of your comment, indeed, those are issues. Although I think I take issue with you pinning this on rustdoc. I actually think it's a dance between documentation presentation (so, rustdoc), API design and familiarity with the language.
I've long said that rustdoc makes unknown unknowns difficult to discover, and this is particularly painful for folks new to Rust. Because you don't really know what to look for yet. And writing docs is a difficult exercise in perspective taking, where you need to balance what you think others know. If you assume they know too little, it's not hard to end up writing too much and adding a fair bit of noise. With that said, I agree that "too little docs" is a far more common problem than "too many docs."
But yeah, your experience is a perfect example of what I mean when I say "generics complicate APIs." They introduce indirection everywhere, and I'm not sure how much rustdoc can really help with that. You might be right that maybe there are some visualizations that can be added, but like you, I've always seen those as gimmicks in other tools that are rarely useful. IMO, a heavily generic API really requires the crate author to write more prose about how their APIs are intended to be used with lots of concrete examples.
The interesting bit here is that I've personally found the documentation experience in Rust to be far far better than any other ecosystem. All the way from writing docs up to consuming them. I've sampled many different ecosystems (C, C++, Haskell, Python, Go to name some) and other than maybe Go, I thought the doc experience was really just not great in any of them. Python specifically seems to be a case where I tend to see a lot of variance in opinion. I hated Sphinx so much, for example, that I built an alternative.[1] I also just generally dislike the output that Sphinx produces. I find that it lacks structure, and I've always had a hard time navigating my way through Python library docs.
[1]: https://github.com/mitmproxy/pdoc
-
What is it that makes Rust documentation so special, and how could we make that lightning strike twice in other languages?
Anyway, this is all my opinion. And a lot of it is based on reflecting on my own experience. I have no idea how well it generalizes. I have given this topic a lot of thought though, and have even written documentation generators for other ecosystems because I thought the other choices were bad enough to warrant spending a few weeks on such a tool.
-
Bombsquad 1.6.11 (20538, 2022-03-23) released
Documentation is now generated using pdoc https://pdoc.dev. Thanks Dliwk!! (I'll get it wired up to auto-update to a webpage soon).
-
My first open-source package on PyPI: `spectrumdevice`, a high-level, object-oriented library for controlling Spectrum Instruments digitisers. A bit of a niche one!
There's a comprehensive README.md with installation and Quickstart information on GitHub, and reference documentation (auto generated by pdoc) on GitHub Pages.
-
Mitmproxy 7.0
Our main docs are built with Hugo (https://github.com/mitmproxy/mitmproxy/tree/main/docs). For our API docs we use pdoc (https://pdoc.dev), which integrates well with most static site generators. pdoc is also maintained by us. :)
-
Things I Wish I Knew as a New Python User
PEP 257 and a few others define "docstrings". Leverage them to make full use of autodoc tools. pdoc is a pretty fun tool that "just works". Build good habits from the start. Projects that have great documentation are just more attractive to me. If I come across a project that seems to do what I need, but has crappy documentation, I keep looking.
-
Show HN: Pdoc, a lightweight Python API documentation generator
Hi HN! Some of you may remember @BurntSushi's pdoc tool, a lightweight alternative to Sphinx. We're a bit in an unfortunate situation with a hostile work assuming our name [1], but I figured that we shouldn't give in and continue the legacy of that tool. Long story short, we have just published a major new "modern Python 3" release, which hopefully makes pdoc a really compelling option again. :-)
[1] https://github.com/mitmproxy/pdoc#pdoc-vs-pdoc3
pre-commit-hooks
-
Implementing Quality Checks In Your Git Workflow With Hooks and pre-commit
# See https://pre-commit.com for more information # See https://pre-commit.com/hooks.html for more hooks repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v3.2.0 hooks: - id: trailing-whitespace - id: end-of-file-fixer - id: check-yaml - id: check-toml - id: check-added-large-files - repo: local hooks: - id: tox lint name: tox-validation entry: pdm run tox -e test,lint language: system files: ^src\/.+py$|pyproject.toml|^tests\/.+py$ types_or: [python, toml] pass_filenames: false - id: tox docs name: tox-docs language: system entry: pdm run tox -e docs types_or: [python, rst, toml] files: ^src\/.+py$|pyproject.toml|^docs\/ pass_filenames: false - repo: https://github.com/pdm-project/pdm rev: 2.10.4 # a PDM release exposing the hook hooks: - id: pdm-lock-check - repo: https://github.com/jumanjihouse/pre-commit-hooks rev: 3.0.0 hooks: - id: markdownlint
-
How to Write Impeccably Clean Code That Will Save Your Sanity
repos: - repo: https://github.com/ambv/black rev: 23.3.0 hooks: - id: black args: [--config=./pyproject.toml] language_version: python3.11 - repo: https://github.com/pycqa/flake8 rev: 6.0.0 hooks: - id: flake8 args: [--config=./tox.ini] language_version: python3.11 - repo: https://github.com/pycqa/isort rev: 5.12.0 hooks: - id: isort args: ["--profile", "black", "--filter-files"] language_version: python3.11 - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.4.0 hooks: - id: requirements-txt-fixer language_version: python3.11 - id: debug-statements - id: detect-aws-credentials - id: detect-private-key
-
Setting Up Pre-Commit Hooks in GitHub: Ensuring Code Quality and Consistency
repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: hooks: - id: check-json
-
Level up your development in Git
$ pre-commit run --all-files [INFO] Initializing environment for https://github.com/pre-commit/pre-commit-hooks. [INFO] Initializing environment for https://github.com/psf/black. [INFO] Installing environment for https://github.com/pre-commit/pre-commit-hooks. [INFO] Once installed this environment will be reused. [INFO] This may take a few minutes... [INFO] Installing environment for https://github.com/psf/black. [INFO] Once installed this environment will be reused. [INFO] This may take a few minutes... Check Yaml...............................................................Passed Fix End of Files.........................................................Passed Trim Trailing Whitespace.................................................Failed - hook id: trailing-whitespace - exit code: 1 Files were modified by this hook. Additional output: Fixing sample.py black....................................................................Passed
-
What happens when you leak AWS credentials and how AWS minimizes the damage
The excellent pre-commit framework (https://pre-commit.com/) has a hook for that in its official hook collection: https://github.com/pre-commit/pre-commit-hooks#detect-aws-cr...
-
Improve your Django Code with pre-commit
exclude: .*migrations\/.* repos: - repo: https://github.com/pre-commit/pre-commit-hooks ... - repo: https://github.com/psf/black rev: 22.12.0 hooks: - id: black language_version: python3.9
-
ChatGPT based PR Reviewer and Summarizer (GH Action)
This is what we use — https://github.com/pre-commit/pre-commit-hooks/blob/main/pre_commit_hooks/detect_private_key.py
-
How I use pre-commit for Terraform
Personally I do also add "end-of-file-fixer" and "trailing-whitespace" from the "https://github.com/pre-commit/pre-commit-hooks" repo. That cleans up and normalizes some files as well.
-
Gitlab CI with docker compose
repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v3.3.0 hooks: - id: check-yaml args: ["--allow-multiple-documents"] - repo: local hooks: - id: forbidden-files name: forbidden files entry: found copier update rejection files; review them and remove them language: fail files: "\\.rej$" - id: black name: black entry: poetry run black language: system types: [python] - id: flake8 name: flake8 entry: poetry run flake8 language: system types: [python] - id: isort name: isort entry: poetry run isort --settings-path=. language: system types: [python] - id: pyupgrade name: pyupgrade entry: poetry run pyupgrade language: system types: [python] args: [--py310-plus] - id: mypy name: mypy description: Check python types. entry: poetry run mypy language: system types: [python]
-
Disable a direct push to GitHub main branch
repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.1.0 hooks: - id: no-commit-to-branch
What are some alternatives?
sphinx - The Sphinx documentation generator
bandit - Bandit is a tool designed to find common security issues in Python code.
MkDocs - Project documentation with Markdown.
pyupgrade - A tool (and pre-commit hook) to automatically upgrade syntax for newer versions of the language.
Pycco - Literate-style documentation generator.
tfsec - Security scanner for your Terraform code [Moved to: https://github.com/aquasecurity/tfsec]
pdocs - A simple program and library to auto generate API documentation for Python modules.
tflint - A Pluggable Terraform Linter
Python Cheatsheet - All-inclusive Python cheatsheet
codespell - check code for common misspellings
pyment - Format and convert Python docstrings and generates patches
terraform-docs - Generate documentation from Terraform modules in various output formats