search

ni / niflexlogger-automation-python

The niflexlogger-automation package contains an API (Application Programming Interface) and examples for using Python to automate NI FlexLogger. The automation API supports modifying the configuration of existing FlexLogger projects and controlling the execution of FlexLogger test sessions. The package is implemented in Python. NI created and supports this package.
MIT License
8 stars 6 forks source link

Update conf.py #20

Closed chadallee closed 2 years ago

chadallee commented 2 years ago

Set linenos style to "table" so that when you select code to copy/paste, it doesn't include the line numbers. Bump sphinx-rtd-theme dependency version to a prerelease version that doesn't include line numbers when you text from the example code blocks.

What does this Pull Request accomplish?

Separates the code from the line numbers in our readthedocs documentation.

Why should this Pull Request be merged?

We've been doing usability studies re: the python API and every user has ended up here: https://niflexlogger-automation.readthedocs.io/en/latest/getting_started.html#examples

When they try to copy/paste the code, it includes line numbers. When they go to delete them, the indentation gets messed up, and python cares a lot about indendtation.

What testing has been done?

Ran tox -e docs on my machine and it looks good now. Before: image

After: image

chadallee commented 2 years ago

Apparently this is a relatively recent regression (reported June 19th): readthedocs/sphinx_rtd_theme#1168

And there has been a fix submitted to the sphinx-rtd-theme repo, but there's not a "stable" release with the fix in it yet. However, version 1.0.0rc1 exists does work: https://pypi.org/project/sphinx-rtd-theme/#history

Also, according to the Sphinx documentation, it seems this html_codeblock_linenos_style flag I added has been deprecated as of "Sphinx 4.0".

So I tested bumping the version of sphinx-rtd-theme in docs/requirements.txt to version ">=1.0.0rc1" and that resolved the issue.

I was worried this would require a script somewhere to explicitly call "pip install --pre" to access prerelease versions, but I tested it and our documentation generation instructions (run tox -e docs​) still worked just fine. It found the pre-release version and the docs generated well.

So updating the required version of that dependency to this prerelease version feels like the right way to fix this. Any objections to that?