Internal API documentation?

[user202729]

Recently, I've been developing some plugins and in the process, have to figure out what several variables/properties does in Plover code.

Is there any way I can write some documentation for Plover?

There's #1174 -- however the documentation is in separate files and that is prone to having outdated information.

I think the best way is to generate the documentation from docstrings in the code itself, then edit the code to include documentation.

There are already docstrings for several objects/functions already, but they mostly suffer from:

• No nice webpages.
• There is little documentation for internal variables/methods, makes it hard to
  • modify Plover source code (I know it's not recommended, but sometimes it's hard to do it right -- also because the documentation is sparse), or
  • use internal methods from plugins.
• There's no type information...
  • both because the docstrings doesn't require it, so normally there's only simple English description,
  • which makes it hard for plugin writers to know what can be done with it, and
  • there's no fixed/well-defined format.
  • I think using Python's built-in type hints is a good option; if compatibility is required, # type: something can be used.
  • It's not necessary to get everything mypy-compatible, just that having some guideline for type annotation ("List[int]") is better than none ("list of integers"?)

[sammdot]

I've been looking into setting up MkDocs or similar to generate documentation, and then moving the docs I wrote in there. Of course I'd also prefer to have the docs within the code, and written in Markdown, so this seems like the best approach. But until then, https://plover.rtfd.io will have to do 😅

[user202729]

I might want to look at this soon.

Once in a while, when I write a plugin that needs some Plover features, I would have to look it up in the Plover source code. And it would be better if I write this down than to forget about it and have to look it up again.

I'm not really experienced in these things (and then, there are too many choices -- Sphinx? MkDocs? pdoc? Do I even know reST?)

[user202729]

Did some initial work. (documentation branch, use Mkdocs)

I prefer type annotation, so this will be incompatible with Plover...

(instruction:

• Download the source code.
• Install it into the Python environment.
• Set the current working directory to the repository root.
• Execute mkdocs serve.
• (optional) mkdocstrings requires running the programs to make the docstrings, so currently I only generate the Linux files. Remove docs/oslayer/xkeyboardcontrol.md and docs/oslayer/xwmctrl.md if it causes error.
• Visit the address displayed on the console.

)

---

mkdocstrings observed problems: (or I don't know how to make them)

• Type annotations are not clickable (such as the KeyboardCapture type name in http://localhost:8000/machine/#plover.machine.keyboard.Keyboard )
• How to reference to a method of the current class? Rewriting the class fully qualified name is quite hard.
• Also, how to reference to a property of a class?
• Is there an automated way to convert the documentation to docstrings etc.? Or Markdown to Sphinx's reST?

[user202729]

The equivalent of mkdocstrings in Sphinx is autodoc.

Some documentation convention should be followed for consistent HTML generation. (and perhaps for mypy type checking too)

There appears to be some choices...

• Sphinx's default
• Google's convention
• Numpy's convention

The latter 2 requires an additional plugin (napoleon?)

Neither are compatible with the current Plover's documentation format.

[user202729]

Looking at the options.

@<developers> What exactly can be included in the code?

• Documentation?
  • In the current documentation format?
  • Google/Numpy style? (Sphinx compatible)
• Type annotation? def f(x: int)->int
• Type hint? x=1 # type: int This doesn't affect version compatibility or anything (but still require import typing), and can be better checked (by mypy for example) than docstring.

[user202729]

Trying autodoc on Config for now.

(running instruction:

• Download https://github.com/user202729/plover/tree/documentation_2 and cd into Plover's home directory.
• pip install sphinxcontrib.yt sphinx-rtd-theme or pip install doc/requirements.txt
• pip install sphinx-autobuild sphinx-autodoc-typehints sphinx-autodoc
• sphinx-autobuild --watch . -b html doc/ /some/output/directory
  for some convenient output directory (it doesn't matter)
• (autobuild can be replaced with build, but autoupdate won't be available in that case)
• Visit http://localhost:8000

)

Is that way (https://github.com/user202729/plover/blob/22a1b7c517ab3a3abcc62cd4df556c9f87bac316/plover/config.py#L372-L381) of writing documentation okay? Or is there other problems of not including type hints in code?

The only problem I can see is with import typing, but

try:
	import typing
except ImportError:
	pass

works just as well (for both mypy and Sphinx)

Using sphinx_autodoc_typehints has the disadvantage that if the arguments are not documented, the type hint information "disappears"

[user202729]

Pushed that branch to (unsurprisingly) https://plover2.readthedocs.io/ .

Sometimes there are duplication between the existing docstring and the new documentation, in that case I keep the better version.

There are some bugs (for instance, how to make this recognized as a type? Or how to change the order of attributes to be not at the top?), but it's readable enough.