Skip to content

Commit fb4d35c

Browse files
dgarcia360dgarcia360
committed
Merge branch 'master' into hide-icons-topic-mobile
2 parents 0a36e7a + 462eab9 commit fb4d35c

19 files changed

Lines changed: 236 additions & 180 deletions

File tree

‎docs/source/conf.py‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,18 @@
88

99
sys.path.insert(0, os.path.abspath(".."))
1010

11+
# -- Global variables
12+
13+
# Build documentation for the following tags and branches
14+
TAGS = []
15+
BRANCHES = ["branch-1.1", "branch-1.0", "master"]
16+
# Set the latest version.
17+
LATEST_VERSION = "branch-1.1"
18+
# Set which versions are not released yet.
19+
UNSTABLE_VERSIONS = ["master"]
20+
# Set which versions are deprecated
21+
DEPRECATED_VERSIONS = [""]
22+
1123
# -- General configuration ------------------------------------------------
1224

1325
# Add any Sphinx extension module names here, as strings.
@@ -59,15 +71,13 @@
5971

6072
# -- Options for multiversion extension ----------------------------------
6173

62-
# Whitelist pattern for tags (set to None to ignore all tags)
63-
TAGS = []
74+
# Whitelist pattern for tags
6475
smv_tag_whitelist = multiversion_regex_builder(TAGS)
65-
# Whitelist pattern for branches (set to None to ignore all branches)
66-
BRANCHES = ["branch-1.1", "branch-1.0", "master"]
76+
# Whitelist pattern for branches
6777
smv_branch_whitelist = multiversion_regex_builder(BRANCHES)
6878
# Defines which version is considered to be the latest stable version.
69-
# Must be listed in smv_tag_whitelist or smv_branch_whitelist.
70-
smv_latest_version = "branch-1.1"
79+
smv_latest_version = LATEST_VERSION
80+
# Defines the new name for the latest version.
7181
smv_rename_latest_version = "stable"
7282
# Whitelist pattern for remotes (set to None to use local branches only)
7383
smv_remote_whitelist = r"^origin$"
@@ -96,6 +106,8 @@
96106
"github_issues_repository": "scylladb/sphinx-scylladb-theme",
97107
"github_repository": "scylladb/sphinx-scylladb-theme",
98108
"site_description": "Sphinx Theme for ScyllaDB projects.",
109+
"versions_unstable": UNSTABLE_VERSIONS,
110+
"versions_deprecated": DEPRECATED_VERSIONS,
99111
}
100112

101113
# Last updated format

‎docs/source/configuration/images/deprecated.png‎

8.77 KB
Loading

‎docs/source/configuration/images/unstable.png‎

8.77 KB
Loading

‎docs/source/configuration/multiversion.rst‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Multiversion Options
44

55
The toolchain adds by default the extension `sphinx-multiversion <https://github.com/dgarcia360/sphinx-multiversion>`_ for building self-hosted versioned documentation.
66

7-
On this page, you’ll learn:
7+
On this page, you will learn:
88

99
- How to list new versions.
1010
- How to define a stable url.
@@ -23,19 +23,16 @@ The settings ``TAGS`` and ``BRANCHES`` in ``conf.py`` defines which versions are
2323

2424
.. tip:: If you maintain a branch for each minor release (e.g. ``branch-3.22``), we recommended building docs for the **branch** and not for tags. This will allow you to backport documentation changes if needed without having to update the tag reference.
2525

26-
The setting ``smv_latest_version`` in ``conf.py`` defines which branch or tag is considered the latest.
26+
The setting ``LATEST_VERSION`` in ``conf.py`` defines which branch or tag is considered the latest.
2727
This is used to redirect users to the latest version of the docs automatically once they open the main project URL.
2828

29-
For example, if you want to build docs for the tags ``3.22.0`` and ``3.21.0``, ``master`` branch, the configuration file conf.py should look like this:
29+
For example, if you want to build docs for the tags ``3.22.0`` and ``3.21.0``, ``master`` branch, the configuration file ``conf.py`` should look like this:
3030

3131
.. code:: python
3232
3333
TAGS = ['3.22.0', '3.21.0']
34-
smv_tag_whitelist = multiversion_regex_builder(TAGS)
3534
BRANCHES = ['master']
36-
smv_branch_whitelist = multiversion_regex_builder(BRANCHES)
37-
38-
smv_latest_version = '3.22.0'
35+
LATEST_VERSION = '3.22.0'
3936
4037
The extension allows configuring additional settings.
4138
To know more about them, refer to `sphinx-multiversion documentation <https://holzhaus.github.io/sphinx-multiversion/master/configuration.html>`_.
@@ -50,9 +47,39 @@ You can override the latest version output directory via the configuration file
5047

5148
.. code:: python
5249
53-
smv_latest_version = 'x.y.z' # Use the branch/tag name
50+
smv_latest_version = LATEST_VERSION # Use the branch/tag name
5451
smv_rename_latest_version = 'stable' # Use the commit hash
5552
53+
Defining unstable versions
54+
--------------------------
55+
56+
Suppose you want to build docs for a version of the software you have not released yet (e.g. ``master``).
57+
In this case, you can mark the version as unstable in the ``conf.py`` file.
58+
59+
.. code:: python
60+
61+
BRANCHES = ['master']
62+
UNSTABLE_VERSIONS = ['master']
63+
64+
By doing so, the warning message that appears at the top of the page will change to:
65+
66+
.. image:: images/unstable.png
67+
68+
Defining deprecated versions
69+
----------------------------
70+
71+
Suppose you want to build docs for a version of the software you don't support anymore.
72+
In this case, you can mark the version as deprecated in the ``conf.py`` file.
73+
74+
.. code:: python
75+
76+
TAGS = ['3.2.0']
77+
DEPRECATED_VERSIONS = ['3.2.0']
78+
79+
By doing so, the warning message that appears at the top of the page will change to:
80+
81+
.. image:: images/deprecated.png
82+
5683
Disabling multiversion support
5784
------------------------------
5885

‎docs/source/configuration/template.rst‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,38 @@ Example:
9191
'tag_substring_removed': '-scylla',
9292
}
9393
94+
Version warning options
95+
-----------------------
96+
97+
Configuration options for version warning.
98+
99+
.. list-table::
100+
:widths: 20 20 20 40
101+
:header-rows: 1
102+
103+
* - Option
104+
- Type
105+
- Default Value
106+
- Description
107+
* - ``versions_unstable``
108+
- list of strings
109+
- []
110+
- List of versions (branches or tags) that are not released yet.
111+
* - ``versions_deprecated``
112+
- list of strings
113+
- []
114+
- List of deprecated versions (branches or tags).
115+
116+
Example:
117+
118+
.. code:: python
119+
120+
html_theme_options = {
121+
'versions_unstable': ['master'],
122+
'versions_deprecated': [],
123+
}
124+
125+
94126
Contribute button options
95127
-------------------------
96128

‎docs/source/examples/hero-box.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ The ``hero-box`` directive supports the following options:
3131
- Description
3232
* - ``title``
3333
- string
34-
- Y
34+
- |v|
3535
- Lorem ipsum
3636
- Hero box title.
3737
* - ``button_icon``
@@ -46,9 +46,9 @@ The ``hero-box`` directive supports the following options:
4646
- Text for the call to action.
4747
* - ``button_url``
4848
- string
49+
-
50+
-
4951
- Relative link or external URL for the call to action. Do not use leading and trailing ("/") symbols to define relative links. (e.g. instead of ``/getting-started/``, use ``getting-started``).
50-
- fa fa-home
51-
- Link to
5252
* - ``image``
5353
- string
5454
-

‎docs/source/examples/panel-box.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ The ``topic-box`` directive supports the following options:
3131
- Description
3232
* - ``title``
3333
- string
34-
- Y
34+
- |v|
3535
- Lorem ipsum
3636
- Hero box title.
3737

‎docs/source/examples/toc.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,13 @@ The :abbr:`TOC (Table of Contents)` is automatically generated in sphinx when yo
1010

1111
Each index.rst needs to have a toctree directive in order to build the left side nav menu.
1212

13-
See the template for more details.
14-
1513
.. code-block:: rst
1614
1715
.. toctree::
1816
:maxdepth: 2
1917
18+
For more details, see `toctree documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`_.
19+
2020
Mini-TOC
2121
--------
2222

‎docs/source/examples/topic-box.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ The ``topic-box`` directive supports the following options:
3131
- Description
3232
* - ``title``
3333
- string
34-
- Y
34+
- |v|
3535
- Lorem ipsum
3636
- Topic box title.
3737
* - ``icon``

0 commit comments

Comments
 (0)