Repository navigation
Conversation
The developer docs for ``relenv.runtime`` have been a five-line ``automodule`` stub since the module was first added. Issue #154 specifically asks for a narrative page covering what relenv does when the interpreter starts up. Rewrite ``docs/source/developer/runtime.rst`` into a 292-line reference walking the full startup pipeline: * the ``relenv.pth`` entry point that lands in the base interpreter's ``site-packages/`` -- the ``.pth`` body quoted verbatim and the reason the ``SourceFileLoader`` dance is used instead of a bare ``import relenv.runtime``; * every step inside ``bootstrap()``, in order, with a one-paragraph rationale for each (``warnings.filterwarnings``, ``sys.RELENV = relenv_root()``, ``setup_openssl``, the ``site.execsitecustomize`` wrap, ``setup_crossroot``, ``install_cargo_config``, ``wrap_venv``, the ``sys.meta_path`` insert, and the 3.13+-only ``wrap_sysconfig('sysconfig')`` call); * the ``RelenvImporter`` meta-path hook: full table of the ten registered wrappers, a worked example using ``wrap_sysconfig`` + ``get_config_var_wrapper`` to show how ``RELENV_PIP_DIR`` toggles the ``BINDIR`` value, and a note on the idempotence pattern that survives ``importlib.reload(site)``; * a field list of every environment variable the runtime consults -- ``RELENV_DEBUG``, ``RELENV_BUILDENV``, ``RELENV_PIP_DIR``, ``RELENV_CROSS``, ``HOST_PYTHON``, ``SSL_CERT_DIR``/``SSL_CERT_FILE``, ``OPENSSL_MODULES``, ``CARGO_HOME``, ``OPENSSL_DIR``, ``RUSTFLAGS``; * a dedicated section on child venvs (gh-161): how ``wrap_venv`` monkey-patches ``venv.EnvBuilder.post_setup`` to drop a ``relenv.pth`` into stdlib-created children so ``bootstrap()`` runs there too, with the stated scope limit (stdlib ``venv`` only). The original ``automodule`` block is preserved at the end of the file so individual function docstrings still render. Depends on PR #349 landing first for the ``wrap_venv`` references to resolve. Verified with ``sphinx-build`` -- no warnings from the new file (the six pre-existing warnings in ``relenv/common.py`` docstrings are unchanged).
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #154.
The developer docs for
relenv.runtimehave been a 5-lineautomodulestub since the module was first added. Issue #154 asks for a narrative page covering what relenv does when the interpreter starts up — this PR delivers it.Depends on #349
The new doc references
wrap_venv(from the gh-161 fix), so this PR should land after #349 merges. Until then the ``:func:`wrap_venv``` references will unresolve.What's in it
Rewrite
docs/source/developer/runtime.rstfrom the stub to a 292-line reference walking the full startup pipeline. Sections:relenv.pth— the.pthbody quoted verbatim fromrelenv/build/common/install.py:44, and the rationale for theSourceFileLoaderdance over a bareimport relenv.runtime(from the comment block atrelenv/runtime.py:64).bootstrap()call chain — nine numbered steps walking the body, each citing file:line. Coverswarnings.filterwarnings,sys.RELENV = relenv_root(),setup_openssl, thesite.execsitecustomizewrap,setup_crossroot,install_cargo_config,wrap_venv, thesys.meta_pathinsert, and the 3.13+-onlywrap_sysconfig('sysconfig')call.RelenvImportermeta-path hook — class description, full table of the 10 registered wrappers (module name → wrapper function), a worked example usingwrap_sysconfig+get_config_var_wrappershowing howRELENV_PIP_DIRtogglesBINDIR, and a note on the__wrapped__idempotence guard that survivesimportlib.reload(site).RELENV_DEBUG,RELENV_BUILDENV,RELENV_PIP_DIR,RELENV_CROSS,HOST_PYTHON,SSL_CERT_DIR/SSL_CERT_FILE,OPENSSL_MODULES,CARGO_HOME,OPENSSL_DIR,RUSTFLAGS.wrap_venv, the absolute-path requirement, and the stdlib-only scope limit.automoduleblock retained so function docstrings still render.Test plan
cd docs && make html— builds cleanly; no new warnings (the 6 pre-existing warnings are all docutils gripes inrelenv/common.pydocstrings).