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
Experimental: moving configuration to sphinx.toml file #14427
base: main
Are you sure you want to change the base?
Conversation
This is a draft PR to move all static configuration from the conf.py file to a toml file.
pyproject.toml
Outdated
@@ -72,6 +72,7 @@ doc = [ | |||
"typing_extensions", | |||
"exceptiongroup", | |||
"ipython[test]", | |||
"toml", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
recommend tomli ; python_version<'3.11'
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So something like this ?
"toml", | |
"toml", | |
"tomli ; python_version<'3.11'" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah, though with that trailing slash, and probably sorted 😊 .
Then the matching import tomllib/import tomli as tomllib
try/except block where it's used.
On the main, reducing A crazy play I've recently considered is to take DRY, declarative project definition to a silly extreme, and unilaterally declare # pyproject.toml
[tool.sphinx-j2]
author = """{{ project['authors'][0]['name'] }}""" ...with the nickel workflow: from pathlib import Path
import json
try:
import tomllib
except ImportError:
import tomli as tomllib
import jinja2
HERE = Path(__file__).parent
ROOT = HERE.parent
PPT = ROOT / "pyproject.toml"
PPT_DATA = tomllib.loads(PPT.read_text(encoding="utf-8"))
globals().update(
json.loads(
jinja2.Template(json.dumps(PPT_DATA["tool"]["sphinx-j2"], indent=2)).render(PPT_DATA)
)
)
# carry on with actual dynamic things... if needed A complaint can be made about oh no, |
Thanks @bollwyvl, this is for another project @melissawm and I are working on. We'd love to manage to move the configurations files of many projects to be declarative so that we can more generally analyse and send automatic update. You can see that as the same as moving from setup.py to pyproject.toml, but for docs, and yes in the short term there will be another layer of indirection. We also thinking of https://github.com/sphinx-toolbox/sphinx-pyproject and have seen that sphinx might also consider static configuration files. |
Great! Doers get stuff done. The sphinx issue (don't even want to link to it) is reminding me of the flake8 discussion around moving config to Taking all the jinja stuff out of that stdlib-only strawman, so one did have to repeat some content, I'd still rather see that optionally managed in
That third-party tool (which, while small, brings in a raft of other third party tools) seems like a mighty big hammer to achieve the same thing. The sticky DX wickets I see are:
|
Yeah, schema and all we agree, and wether it's in |
Sure, that file would always win, as it's more precise, and is much easier to get good DX from a single-purpose file with taplo in the loop.
That's the magic of the Wild West globals.update(*ppt["tool"]["sphinx-with-arbitary-sections"].values()) which consumed: [tool.sphinx-with-arbitrary-sections]
short-section = { some_key = "foo" }
[tool.sphinx-with-arbitrary-sections.fat-section]
some_other_value = "bar" This would yield a far more readable schema (and instance), and would handle the all-but-inevitable case of conflicting keys defined by different, un-namespaced extensions... and here the
Yeah... that's... extremely optimistic. Just spent a while in |
# relative to the source/ directory. | ||
exclude_patterns = config["sphinx"]["exclude_patterns"] | ||
# The name of the Pygments (syntax highlighting) style to use. | ||
pygments_style = config["sphinx"]["pygments_style"] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm wondering if locals().update(config["sphinx"])
would work for most (all?) of that stuff.
for k, v in intersphinx_mapping.items(): | ||
intersphinx_mapping[k] = tuple( | ||
[intersphinx_mapping[k]["url"], intersphinx_mapping[k]["fallback"]] | ||
) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Obviously here we need some workaround, and updating locals won't work.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thought on publishing (and maintaining an up to date) intersphinx_mapping python package that just contain standard urls for most of the scientific Python stack ? This has no reasons to differ between proejcts right ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I guess that works only if all the packages always point to latest/stable, but that woudl be a good default I think.
[latex] | ||
latex_documents = [ | ||
['index', 'ipython.tex', 'IPython Documentation', | ||
'The IPython Development Team', 'manual', 'True'], | ||
['parallel/winhpc_index', 'winhpc_whitepaper.tex', | ||
'Using IPython on Windows HPC Server 2008', | ||
"Brian E. Granger", 'manual', 'True'] | ||
] | ||
latex_use_modindex = "True" | ||
latex_font_size = "11pt" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I completely forgot we had latex/pdf output. I think we can/should nuke it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, it's not building. I think we will be able to nuke all tex-specific configs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think keeping it for testing purposes may be helpful, tbh. Other projects still do rely on it so it's something to keep in mind long-term.
(not worried about the |
This is a draft PR to move all static docs configuration from the conf.py file to a toml file.
I did things in the simplest way possible since I figure it's no use trying to optimize this now.
cc @Carreau