Use pdoc rather than pdoc3

[frankplow]

Is your feature request related to a problem? Please describe. pdoc and pdoc3 are both continuations of a discontinued pdoc project. The two packages are conflicting. At present, mbed-tools uses pdoc3, however pdoc is a larger and more maintained library, also pdoc3 is the subject of some controversy.

Describe the solution you'd like Change the project to depend on pdoc rather than pdoc3. As far as I can tell, this should be a near drop-in replacement, with just a handful of pdoc3s needing to be changed to pdocs.

Describe alternatives you've considered The installation instructions say

We recommend installing mbed-tools in a Python virtual environment to avoid dependency conflicts.

Doing so mitigates this issue, but I think installation should be made as easy as possible without requiring a virtual environment.

[rwalton-arm]

Thanks. We weren't aware of this. I've raised a PR to remove pdoc3 and its generated documentation. Moving to pdoc isn't a simple find and replace, the pdoc tool works differently to pdoc3. We'll look into alternative docs generation tools in a follow-up.

[Patater]

Removed pdoc3 in https://github.com/ARMmbed/mbed-tools/pull/325

We haven't moved to pdoc yet, so leaving this open.

[dirkroorda]

I have a big nest of documentation of a Python package. I started with read-the-docs, years later I switched to mkdocs, and finally, blissfully unaware of any controversy I went to pdoc3. That has served me well, so well in fact that I also moved my narrative docs to pdoc3, by making a pseudo module about in my python package and writing all my narratives as submodules of that package. These modules only have a docstring, but no python code.

Seeing the controversy and the use of the swastika by @kernc, I thought: what is the fuss about and do I have to switch?

Two observations:

1. pdoc is much poorer than pdoc3. I got pdoc to generate my docs, but I had to pass through unhandled exceptions, unworkable errors, and had to look into the code. And then the result looked definitely worse, especially in the realm of image display. Also, admontitions are not supported. No way to get the docs unscathed into pdoc.

Also, converting to mkdocs with mkdocstrings is a long way to go, it will require very many edits in my docs.

2. It appears that the swastika is not intended as a Nazi symbol. Yet I find it an unlucky choice, but at the same time I like people who cling stubbornly to an older semantics of things before the mob took hold of it. This BBC article explains it well: https://www.bbc.com/culture/article/20210816-the-ancient-symbol-that-was-hijacked-by-evil

Then, he really did a good job to turn a languishing pdoc into a well-working, reliable tool.

The conflict with the original author of pdoc is something that exists, but that I cannot judge. Certainly I do not see any intention on @kernc's part to steal anything. He encountered ideas that he liked, and moved their implementation forward in order to use it and to let it be used by everyone.

For me, that is "end of story" in the sense that I continue to happily use pdoc3.