Simplify conf.py and RST to prep for Furo vs Pytorch config #268
Conversation
example_docs/docs/conf.py
Outdated
|
|
||
| import qiskit_sphinx_theme | ||
| sys.path.insert(0, os.path.abspath('..')) |
There was a problem hiding this comment.
Using .. rather than . because this makes #265 simpler.
|
|
||
| release = qiskit_sphinx_theme.__version__ |
There was a problem hiding this comment.
We now hardcode the release version. I don't think it makes a big difference having the actual version vs. 9.99 in these example docs.
I can add this back if you disagree though
| app.setup_extension('docs.language_utils') |
There was a problem hiding this comment.
Corresponds to the sys.path change from above.
Eric-Arellano
changed the title
| # A boolean that decides whether module names are prepended to all object names | ||
| # (for object types where a “module” of some kind is defined), e.g. for | ||
| # py:function directives. | ||
| add_module_names = False |
There was a problem hiding this comment.
I deleted this. It didn't do anything in the example docs. I think it was copy pasta from another repo.
| # (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F). | ||
| # This can be handy if you document a project that consists of a single | ||
| # package. Works only for the HTML builder currently. | ||
| modindex_common_prefix = ['qiskit.'] |
There was a problem hiding this comment.
I deleted this. It didn't do anything in the example docs. I think it was copy pasta from another repo.
| html_context = { | ||
| # toggle analytics | ||
| # Add "Was this page useful?" to the footer. |
There was a problem hiding this comment.
so this is technically true specifically for this example docs conf.py but in production (i.e. for pages live at qiskit.org domains) this also tracks data relating to page views. I'm not sure if we really need to specify the difference in functionality in the comment here or not 🤔 I guess we've probably explained it enough in the README, but I get nervous sometimes about ensuring we're being as transparent as possible about data/analytics tracking. I'd say it would be a nice-to-have to explicitly mention the analytics/data tracking element of this here, but it's not blocking the PR
There was a problem hiding this comment.
I can fix this in a follow up PR :)
We plan to land the Furo proof of concept soon (#233), so that people can more easily finish Qiskit-ifying the theme.
We have to set slightly different conf.py values, like
html_theme_options. We'll do that by something like this:So, this is prework to make
conf.pyas simple as possible before adding new complexity.--
This also removes the unnecessary
.. contents::directives from some pages. They didn't actually do anything, but cause a huge warning when using Furo. With Pytorch, we still have our right page-level table of contents even without it.