Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

NixOS Python test driver: Python package and Sphinx docs #73496

Closed
wants to merge 4 commits into from

Conversation

@FRidh
Copy link
Member

FRidh commented Nov 16, 2019

Motivation for this change
Things done
  • Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
  • Built on platform(s)
    • NixOS
    • macOS
    • other Linux distributions
  • Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
  • Tested compilation of all pkgs that depend on this change using nix-shell -p nix-review --run "nix-review wip"
  • Tested execution of all binary files (usually in ./result/bin/)
  • Determined the impact on package closure size (by running nix path-info -S before and after)
  • Ensured that relevant documentation is up to date
  • Fits CONTRIBUTING.md.
Notify maintainers

cc @

pushd doc
make html
mkdir -p "$devdoc"
mv _build/html "$devdoc"

This comment has been minimized.

Copy link
@FRidh

FRidh Nov 16, 2019

Author Member

Any suggestion for how the full path should look?

FRidh added 4 commits Nov 16, 2019
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.
return self.booted and self.connected

def log(self, msg: str) -> None:
"""Log the given ``msg``.

This comment has been minimized.

Copy link
@Mic92

Mic92 Nov 16, 2019

Contributor

Does Sphinx also shows type annotations these days?

This comment has been minimized.

Copy link
@FRidh

FRidh Nov 16, 2019

Author Member

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.

@FRidh
Copy link
Member Author

FRidh commented Nov 16, 2019

To check it out,

cd nixos/lib && firefox $(nix-build -A testDriver.devdoc testing-python.nix)/html/index.html
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}

This comment has been minimized.

Copy link
@tfc

tfc Nov 17, 2019

Contributor

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'),
]

This comment has been minimized.

Copy link
@tfc

tfc Nov 17, 2019

Contributor

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!

This comment has been minimized.

Copy link
@tfc

tfc Nov 17, 2019

Contributor

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"

This comment has been minimized.

Copy link
@tfc

tfc Nov 17, 2019

Contributor

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)

This comment has been minimized.

Copy link
@Mic92

Mic92 Nov 17, 2019

Contributor

It could be re-imported from the module.

@@ -131,6 +139,8 @@ def retry(fn: Callable) -> None:


class Logger:
"""Logger class."""

This comment has been minimized.

Copy link
@tfc

tfc Nov 17, 2019

Contributor

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.

This comment has been minimized.

Copy link
@FRidh

FRidh Nov 24, 2019

Author Member

The text is indeed useless and is merely for getting something in shown in Sphinx. Writing docstrings is out of scope.

@tfc
Copy link
Contributor

tfc commented Nov 25, 2019

To check it out,

cd nixos/lib && firefox $(nix-build -A testDriver.devdoc testing-python.nix)/html/index.html

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.

@stale
Copy link

stale bot commented Jun 1, 2020

Thank you for your contributions.
This has been automatically marked as stale because it has had no activity for 180 days.
If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.
Here are suggestions that might help resolve this more quickly:

  1. Search for maintainers and people that previously touched the
    related code and @ mention them in a comment.
  2. Ask on the NixOS Discourse. 3. Ask on the #nixos channel on
    irc.freenode.net.
@stale stale bot added the 2.status: stale label Jun 1, 2020
@FRidh
Copy link
Member Author

FRidh commented Jun 1, 2020

I am not pursuing this any further.

@FRidh FRidh closed this Jun 1, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants
You can’t perform that action at this time.