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

support prolog (& epilog) content #190

Open
chrisjsewell opened this issue Jul 22, 2020 · 9 comments
Open

support prolog (& epilog) content #190

chrisjsewell opened this issue Jul 22, 2020 · 9 comments
Labels
enhancement New feature or request

Comments

@chrisjsewell
Copy link
Member

Is there a way to pur the role definition in the conf.py configuration file ? Idealy this should not be in content source file.

Originally posted by @SG-phimeca in #188 (comment)

This would be similar to https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog. An important difference though would be that the content should be injected after any YAML front matter (perhaps there could also be a separate option to add to this front matter)

@chrisjsewell chrisjsewell added the enhancement New feature or request label Jul 22, 2020
@chrisjsewell
Copy link
Member Author

It would also be idea to offer it as a template like construct, similar to https://nbsphinx.readthedocs.io/en/0.3.0/prolog-and-epilog.html, such that one could adjust the behaviour based on variables like the docname

@chrisjsewell
Copy link
Member Author

chrisjsewell commented Dec 17, 2020

Although not specifically addressed, #273 provides a close solution to this, for example:

in conf.py

myst_substitutions = {
   "prolog": """
    <meta property="og:site_name" content="Homepage and blog of Hynek Schlawack">
    <meta property="og:author" content="Hynek Schlawack">
    <meta property="og:type" content="article">
    <meta property="og:title" content="Waiting in asyncio">
    <meta property="og:description" content="One of the main appeals of using Python’s asyncio is being able to fire off many coroutines and run them concurrently. How many ways do you know for waiting for their results?">
    <meta property="og:url" content="https://hynek.me/articles/waiting-in-asyncio/">
    <meta property="article:published_time" content="2020-05-21T00:00:00Z">
    <meta name=twitter:card content="summary">
    <meta name=twitter:site content="@hynek">
    <meta name=twitter:creator content="@hynek">
    <meta name=twitter:image content="https://hynek.me/img/avatar.jpg">
    <meta name=twitter:title content="Waiting in asyncio">
    <meta name=twitter:description content="One of the main appeals of using Python’s asyncio is being able to fire off many coroutines and run them concurrently. How many ways do you know for waiting for their results?">
"""
}

then in each file you would add at the top

{{ prolog }}

@choldgraf
Copy link
Member

choldgraf commented Dec 17, 2020

wait where is this myst_substitutions dark magic documented? I just did a search for myst_substitutions in the parser docs and didn't find it, that is cool! Is there a way to do this within-page in order to have a MyST version of rST substitutions?

EDIT: nvm I read this issue before seeing the others about substitution syntax being added, will comment there

@renefritze
Copy link

Although not specifically addressed, #273 provides a close solution to this, for example:

in conf.py

myst_substitutions = {
   "prolog": """
SNIP
"""
}

then in each file you would add at the top

{{ prolog }}

I've tried this with a substitution that contains a code-cell directive. Am I doing something wrong if that results in this kind of warnings?

WARNING: Found an unexpected `code-cell` directive. Either this file was not converted to a notebook, because Jupytext header content was missing, or the `code-cell` was not converted, because it is nested. See https://myst-nb.readthedocs.io/en/latest/use/markdown.html for more information.

If using a code-cell simply isn't supported atm, is there a workaround?

@mforbes
Copy link

mforbes commented Sep 22, 2021

This might not be the correct place to ask, but can substitutions like {{ prolog }} be used in template files (like _templates/layout.html)? It seems like Jinja is run on these before myst_substitutions is parsed or used. Please let me know if I am missing something, or if I should open a new issue. Thanks.

@executablebooks executablebooks deleted a comment from choldgraf Sep 22, 2021
@chrisjsewell
Copy link
Member Author

but can substitutions like {{ prolog }} be used in template files (like _templates/layout.html)?

Heya, no not directly, since they have completely different "contexts", i.e. the dictionary that maps the variables to their values.
The one for the templates can be added to via https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context

So maybe you could try something like this in your conf.py

myst_substitutions = {"a": "b"}
html_context = {"myst": myst_substitutions}

then use {{ myst.prolog }} in the template file

@mforbes
Copy link

mforbes commented Sep 22, 2021

@chrisjsewell Thanks! This makes sense and is probably the right thing - I realize I was abusing myst_substitutions (I had HTML specific things that make more sense in html_context). I will make a PR with a doc update when I get a chance.

@chrisjsewell
Copy link
Member Author

cheers!

@dbitouze
Copy link

dbitouze commented Dec 6, 2022

[...]

then in each file you would add at the top

{{ prolog }}

Not ideal when you have about thousand files in your documentation...

mforbes pushed a commit to WSU-Physics-Courses/physics-521-classical-mechanics that referenced this issue Dec 25, 2023
It does not look liket myst_substitutions have been initialized when these
get parsed.  See executablebooks/MyST-Parser#190

--HG--
branch : solutions
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

5 participants