Readit NewsThere's a workaround for this case (relevant issue has a link at the top), which is cool, but it uses an "internal" function to solve it, which is not.
But there is one blemish.
They write on documenting variable assignments which don't support pythons __doc__ string:
> To compensate, pdoc will read the abstract syntax tree (an abstract representation of the source code) and include all assignment statements immediately followed by a docstring
I can't really understand that. I am programming Python for 14 years now, and any real codebase I have ever seen documents variables above their declaration. Even if there is some technical reason for it, if I saw a python developer comment what a variable declaration means below that declaration I would at least question their taste.
To me that particular implementation is so bad, that I would prefer pdoc without it.
Are there any libraries similar to Doxylink [2] that ensure that links from Sphinx to pdoc (and vice versa) are valid?
[1] https://news.ycombinator.com/item?id=25903595
[2] https://sphinxcontrib-doxylink.readthedocs.io/en/stable/
There is no pdoc-specific library for link checking as far as I'm aware. It's all plain HTML though, so you can use a more general tool like https://lychee.cli.rs/. :)
That's not true for local capture mode: https://mitmproxy.org/posts/local-capture/linux/. :)
Putting aside the fact that the mechanisms underpinning Github Actions are a mystery black box, the vast vast vast majority of github workflows are not built in a reproducible way - it's not even something that's encouraged by Github Actions' architecture, which emphasises Actions' container images that are little more than packaged installer scripts that go and download dependencies from random parts of the internet at runtime. An "attestation" makes no guarantee that one of these randomly fetched dependencies hasn't been usurped.
This is not to go into the poor security record of Github Actions' permissions model, which has brought us all a number of "oh shit" moments.
I much prefer the way Rust did it, so just a separate type of comment-prefix for docstrings. In Rust a regular comment may be
while a docstring is simply with //! for docstrings at a module level. This is elegant. This is simple. It is a pythonic solution. Treating comments below a variable declaration implicity as a docstring is not. At the beginning of class or function declarations, ok (although I also would have prefered that to be above the declaration), but this.. I need a drink.