Parse messages with reStructuredText

[humitos]

Messages from versionwarning_messages config option are parsed with reStructuredText. This way we can use all its potential to generate the final message.

Closes #5

[humitos]

@sloria I just created this PR that I think it does what you need.

There is an example of this live at https://sphinx-version-warning-example.readthedocs.io/en/0.2.x/

Its conf.py file looks like:

versionwarning_messages = {
    '0.0.1': 'This is a custom message only for version 0.0.1 of this documentation',
    '0.2.x': 'This is a **pre-release**. For 0.0.x see `here </en/0.0.4/>`_',
}

With this PR, the messages are parsed as reStructuredText, so you can use whatever you want there.

If you want to test it in your project install this version:

https://github.com/humitos/sphinx-version-warning/archive/rst-messages.zip

Let me know if this is what you need and I will make a new release of this extension.

[sloria]

Thank! I can't test this right now, but at a glance it is what we need for marshmallow.

[humitos]

@sloria 0.2.0 has been released and it should be able to fulfil your needings. Let me know!

[sloria]

Thanks! I'll try to test it out sometime this week.

[humitos]

@sloria I just tested this with your project.

Stable (Tag 2.15.4):

Latest:

2.x-line:

3.0:

I hope this is what you need.

These are the changes that I've done in your repository:

diff --git a/docs/conf.py b/docs/conf.py
index ae49aae..20f0f6a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -35,6 +35,7 @@ extensions = [
     'sphinx.ext.viewcode',
     'alabaster',
     'sphinx_issues',
+    'versionwarning',
 ]
 
 primary_domain = 'py'
@@ -46,6 +47,13 @@ intersphinx_mapping = {
 
 issues_github_path = 'marshmallow-code/marshmallow'
 
+versionwarning_messages = {
+    'stable': 'This is the latest stable release. For 3.0, see `here </en/3.0/>`_',
+    '2.x-line': 'This is the latest stable release. For 3.0, see `here </en/3.0/>`_',
+    'latest': 'This is a pre-release. For 2.0, see `here </en/2.x-line/>`_',
+    '3.0': 'This is a pre-release. For 2.0, see `here </en/2.x-line/>`_',
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 1f38662..b23f2e6 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,4 @@
 sphinx==1.7.6
 sphinx-issues==1.0.0
 git+https://github.com/sloria/alabaster.git@sloria
+sphinx-version-warning

NOTE: I just removed the project (my fork) from RTD since it was a test only.

[sloria]

Excellent! That's a huge help. Thanks @humitos .

Is there a way to change the color of the banner? Also, is there a way to have the text be on one line, like in Flask's docs?

[humitos]

Is there a way to change the color of the banner? Also, is there a way to have the text be on one line, like in Flask's docs?

Yes to both.

In fact, your project is already changing the colour. By default it's red and in your theme it's yellow.

This can be achieved by adding custom CSS to your project. This guide could be useful: https://docs.readthedocs.io/en/latest/guides/adding-custom-css.html

Also, in case you don't like the HTML structure, you can use versionwarning_banner_html to set whatever you want. By default, it's:

<div id="version-warning-banner" class="admonition warning">
    <p class="first admonition-title">Warning</p>
        <p class="last">
            You are not reading the most up to date version of this documentation. <a href="#"></a> is the newest version.
        </p>
</div>

NOTE: versionwarning_banner_html is only useful for the banner added dynamically by Javascript. On the other hand, if the banner is added statically (using versionwarning_messages), this is done by docutils and its HTML structure is exactly the same than the default value for versionwarning_banner_html.

[humitos]

@sloria Flask, and all pallets projects, are using a custom theme: pallets_sphinx_themes (https://github.com/pallets/flask/blob/rtd/docs/conf.py#L39)

Although, I created a quick n' dirty example at https://sphinx-version-warning-example.readthedocs.io/en/flask-like-warning/ that you can check out.

Hope it helps!

[sloria]

@humitos That's super helpful. Thanks a lot. I think I like the Flask banner the best, so I'll probably adapt that for marshmallow when I get some time.