NixOS Python test driver: Python package and Sphinx docs #73496
Conversation
FRidh
added
6.topic: python
6.topic: nixos
| pushd doc | ||
| make html | ||
| mkdir -p "$devdoc" | ||
| mv _build/html "$devdoc" |
There was a problem hiding this comment.
Any suggestion for how the full path should look?
This commit packages the test driver as a Python package. While it is initially more complicated, this will be worth it as the test driver grows.
Add the impure currentSystem for convenience when testing/building the driver.
FRidh
force-pushed
the
nixos-test-driver
branch
from
4e83ba6 to
94c6b6a
Compare
ofborg
bot
added
8.has: documentation
| return self.booted and self.connected | ||
|
|
||
| def log(self, msg: str) -> None: | ||
| """Log the given ``msg``. |
There was a problem hiding this comment.
Does Sphinx also shows type annotations these days?
There was a problem hiding this comment.
Yes, it includes the type hints in the function declaration just like you now write them. It won't put them in the Parameters list though.
|
To check it out, |
| # Latex figure (float) alignment | ||
| # | ||
| # 'figure_align': 'htbp', | ||
| } |
There was a problem hiding this comment.
All the comments are from (automatically generated) template configs, right?
I suggest to remove all the unneeded outcommented hints and documentation as it will probably outdate anyway.
| latex_documents = [ | ||
| (master_doc, 'NixOStestdriver.tex', 'NixOS test driver Documentation', | ||
| 'Nixpkgs contributors', 'manual'), | ||
| ] |
There was a problem hiding this comment.
did you run black over this file? If not, please do.
| You can adapt this file completely to your liking, but it should at least | ||
| contain the root `toctree` directive. | ||
| Welcome to NixOS test driver's documentation! |
There was a problem hiding this comment.
is this the title that would be printed on top of the whole document? If so - how about simply making this NixOS Test Driver Documentation
| NixOS test driver | ||
| ================= | ||
| """ | ||
| __version__ = "0.1" |
There was a problem hiding this comment.
is there some way to give the driver a central version number that can be reused so we have only one definition? (e.g. nixos/lib/test-driver/nixos_test_driver/doc/conf.py has such a field, too)
There was a problem hiding this comment.
It could be re-imported from the module.
| @@ -131,6 +139,8 @@ def retry(fn: Callable) -> None: | |||
|
|
|||
|
|
|||
| class Logger: | |||
| """Logger class.""" | |||
There was a problem hiding this comment.
I understand that these fields are needed and it is an extra-burden to document undocumented things just to make sphinx work. The text here is however completely redundant and it would be awesome to have an actual explanation how/what/why this exists/works. If you feel this is too much for this pull request, we should make it a ticket.
There was a problem hiding this comment.
The text is indeed useless and is merely for getting something in shown in Sphinx. Writing docstrings is out of scope.
Will this hint be put somewhere in the documentation or so? I can imagine that especially beginners will not find it at first if it's not included in the standard documentation of neither nixos nor nixpkgs. |
|
Thank you for your contributions.
|
stale
bot
added
the
2.status: stale
|
I am not pursuing this any further. |
Motivation for this change
Things done
sandboxinnix.confon non-NixOS linux)nix-shell -p nix-review --run "nix-review wip"./result/bin/)nix path-info -Sbefore and after)Notify maintainers
cc @