You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Read and parse CLI ``--branches`` option
* Process the selected and excluded branches.
* Refactor: Moved the function responsible for getting all versions to `GitVersions`
* testing infra for branch selection
* simplify branch selection for maintainability
* moved branch selection infra to `sphinx_versioned.lib`.
* Modified gh-action to accomodate branch selection/exclusion.
* updated docstrings
* updated documentation
* changelog
Copy file name to clipboardExpand all lines: docs/tutorial.rst
+61-23Lines changed: 61 additions & 23 deletions
Original file line number
Diff line number
Diff line change
@@ -12,6 +12,33 @@ Make sure that you've already :ref:`installed <install>` it.
12
12
Building versioned docs
13
13
=======================
14
14
15
+
.. _initializing_sphinx:
16
+
17
+
Initializing project with sphinx and git
18
+
----------------------------------------
19
+
20
+
If you have problems initializing sphinx and git, then follow these instructions, otherwise you can skip directly to :ref:`initializing sphinx-versioned-docs <initializing_versioned_docs>`
21
+
22
+
Before we begin make sure you have `sphinx <https://pypi.org/project/Sphinx/>`__ install and some git history already in your project.
23
+
If not, read `first steps with sphinx <http://www.sphinx-doc.org/en/stable/tutorial.html>`_ first.
24
+
If you just want something quick and dirty you can do the following:
25
+
26
+
.. code-block:: console
27
+
28
+
$ sphinx-quickstart docs -p projectname -a author -v version --makefile --no-sep -r version -l en -q
29
+
$ git checkout -b feature_branch main # Create new branch from main.
Before using the ``sphinx-versioned-docs`` to build a versioned documentation. Make sure you have following things done:
16
43
17
44
- [x] Project initialized.
@@ -33,49 +60,60 @@ you can run the following command to generate the versioned documentation:
33
60
34
61
$ sphinx-versioned
35
62
36
-
-----------------
63
+
If you have problems initializing project and running sphinx, then follow at :ref:`initializing sphinx and git <initializing_sphinx>`.
37
64
38
-
If you have problems initializing sphinx and git, then follow these instructions:
65
+
------------------------------
39
66
40
-
Before we begin make sure you have some Sphinx docs already in your project. If not, read `First Steps with Sphinx <http://www.sphinx-doc.org/en/stable/tutorial.html>`_ first. If you just want something quick
41
-
and dirty you can do the following:
67
+
Generated output
68
+
----------------
42
69
43
-
.. code-block:: console
70
+
After the build has succeded, your docs should be available in ``<output directory>/<branch>/index.html`` with a version selector menu/badge present.
44
71
45
-
$ sphinx-quickstart docs -p projectname -a author -v version --makefile --no-sep -r version -l en -q
46
-
$ git checkout -b feature_branch main # Create new branch from main.
By default, ``sphinx-versioned-docs`` pre-builds the branches to see which of them fails; but this behaviour can be mitigated using the ``--no-prebuild`` argument.
51
75
52
-
$ sphinx-versioned
76
+
.. note::
53
77
54
-
------------------------------
78
+
Use ``--no-quite`` option to get output from the sphinx builder, adjust verbosity using ``-v``
79
+
80
+
---------------------------
81
+
82
+
Selecting/ Excluding branches and tags
83
+
--------------------------------------
55
84
56
85
By default, ``sphinx-versioned-docs`` will try to build all tags and branches present in the git repo.
57
-
However, to build some particular branch(s) and tag(s), they can be specified in the ``--branches`` argument as:
86
+
However, this behaviour can be augmented using the ``--branch`` command-line-argument, to build/exclude
87
+
some particular branch(s) and tag(s), they can be specified in the ``--branch`` argument as:
58
88
59
-
.. code-block:: console
89
+
#. **For selecting a branch:** mention the branch/tag name in the CLI arugment like:
60
90
61
-
$ sphinx-versioned --branches "main, docs"
91
+
.. code-block:: console
62
92
63
-
This command will build the ``main`` and ``docs`` branches.
64
-
More such options are available at :ref:`options <settings>`.
93
+
$ sphinx-versioned --branch "main,v2.0"
94
+
$ sphinx-versioned --branch "+main,+v2.0"
65
95
96
+
Either of the two options above will select ``main``, ``v2.0`` and will only build these.
66
97
98
+
#. **For excluding a branch:** mention the branch/tag name with ``-`` in the CLI argument like:
67
99
68
-
After the build has succeded, your docs should be available in ``<output directory>/<branch>/index.html`` with a version selector menu/badge present.
100
+
.. code-block:: console
69
101
70
-
.. note::
102
+
$ sphinx-versioned --branch "-main,-v2.0"
71
103
72
-
By default, ``sphinx-versioned-docs`` pre-builds the branches to see which of them fails; but this behaviour can be mitigated using the ``--no-prebuild`` argument.
104
+
The above command will build all available branches and tags except ``main``, ``v2.0``
73
105
74
-
.. note::
106
+
#. **For selecting and excluding simultaneously:** mention the branch/tag name with ``-`` in the CLI argument like:
75
107
76
-
Use ``--no-quite`` option to get output from the sphinx builder, adjust verbosity using ``-v``
108
+
.. code-block:: console
77
109
78
-
---------------------------
110
+
$ sphinx-versioned --branch "main,-v2.0"
111
+
112
+
The above command will only build ``main`` and will exclude ``-v2.0`` (untouched because the package was only building ``main``).
113
+
114
+
More such options are available at :ref:`options <settings>`.
0 commit comments