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

Add documentation testing #902

merged 4 commits into from Jul 8, 2022


Copy link

@kurtmckee kurtmckee commented Jul 7, 2022

This introduces the following changes:

  • Sphinx is now a test requirement.
  • tox now tests HTML documentation builds. Warnings are escalated to errors.
  • GitHub CI now tests HTML documentation builds.
  • A single warning that occurs during HTML doc builds is now fixed.

Testing the documentation helps identify build errors before publication. In this case, the tests caught a rendering problem that is visible in the current documentation, which prevented Sphinx from substituting watchdog for |project_name| in a code example on the Installation page:

$ python -m pip install -U watchdog

# or to install the watchmedo utility:
$ python -m pip install -U |project_name|[watchmedo]

Copy link

BoboTiG commented Jul 8, 2022

Is it enough to fix #898 also?

Copy link
Contributor Author

I reviewed #898 but didn't tag it here because I don't think this PR addresses the root issue in that PR. However, this PR does lay the groundwork for addressing that, as well.

This PR tests HTML generation; #898 is about man page generation. I can augment this PR to try addressing that concern as well (in fact I need to update this PR to fix merge conflicts in tox.ini anyway).

I'll be able to circle back to this shortly.

Copy link
Contributor Author

kurtmckee commented Jul 8, 2022

The merge conflict is resolved.

I noticed that #898 is turning on nitpick mode (the -n option). When I enabled that for the HTML build I found that there is a class of error that I don't see a way to fix without rearchitecting the code itself. In particular, the module docstring for watchdog/observers/ includes relative :class: references to each of the system-specific observers. However, some of those modules will raise exceptions just be importing them on the wrong system, so Sphinx cannot consistently reach into those modules and link to the Observer classes in them.

As another example, there isn't a way to reference :class:`queue.Empty` because it's not part of the watchdog documentation -- it's a stdlib class. This could be converted to a simple monospace reference like ``queue.Empty``, or it could be converted to an external link to the Python stdlib.

I may be able to swing back around to start dealing with these classes of issues by simply removing or downgrading these types of references, but for now, this PR lays the groundwork to enable that future cleanup work.

@BoboTiG BoboTiG merged commit eb331de into gorakhargosh:master Jul 8, 2022
19 of 23 checks passed
@kurtmckee kurtmckee deleted the add-doc-testing branch July 8, 2022 20:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
None yet

Successfully merging this pull request may close these issues.

None yet

2 participants