1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
Contributing to the documentation
=================================
Here are some tips for working on this documentation. You're welcome to add
more and help us out!
First of all, you should check the `reStructuredText (reST) Primer
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ to learn how
to write your .rst file.
Create a .rst file
---------------------
Look at the structure and choose the best category to put your .rst file. Make
sure that it is referenced in the index of the corresponding category, so it
will show on in the documentation. If you have no idea how to do this, study
the other index files for clues.
Build documentation locally
---------------------------
.. Docs are always built on Python 3.12. See also the RTD and tox config.
To build the documentation locally, :ref:`set up a development environment
<setup-dev-environment>`. However, you **must** have a Python 3.12 interpreter installed
and available on your path (i.e., ``python3.12`` must start a Python 3.12 interpreter).
You'll also need to install the Enchant spell checking library.
.. tabs::
.. group-tab:: macOS
Enchant can be installed using `Homebrew <https://brew.sh>`__:
.. code-block:: console
(venv) $ brew install enchant
If you're on an Apple Silicon machine, you'll also need to manually set the location
of the Enchant library:
.. code-block:: console
(venv) $ export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.2.dylib
.. group-tab:: Linux
Enchant can be installed as a system package:
**Ubuntu 20.04+ / Debian 10+**
.. code-block:: console
$ sudo apt-get update
$ sudo apt-get install enchant-2
**Fedora**
.. code-block:: console
$ sudo dnf install enchant
**Arch, Manjaro**
.. code-block:: console
$ sudo pacman -Syu enchant
.. group-tab:: Windows
Enchant is installed automatically when you set up your development
environment.
Once your development environment is set up, run:
.. tabs::
.. group-tab:: macOS
.. code-block:: console
(venv) $ tox -e docs
.. group-tab:: Linux
.. code-block:: console
(venv) $ tox -e docs
.. group-tab:: Windows
.. code-block:: doscon
(venv) C:\...>tox -e docs
The output of the file should be in the ``docs/_build/html`` folder. If there
are any markup problems, they'll raise an error.
Live documentation preview
--------------------------
To support rapid editing of documentation, Briefcase also has a "live preview" mode:
.. tabs::
.. group-tab:: macOS
.. code-block:: console
(venv) $ tox -e docs-live
.. group-tab:: Linux
.. code-block:: console
(venv) $ tox -e docs-live
.. group-tab:: Windows
.. code-block:: doscon
(venv) C:\...>tox -e docs-live
This will build the documentation, start a web server to serve the build documentation,
and watch the file system for any changes to the documentation source. If a change is
detected, the documentation will be rebuilt, and any browser viewing the modified page
will be automatically refreshed.
Documentation linting
---------------------
Before committing and pushing documentation updates, run linting for the
documentation:
.. tabs::
.. group-tab:: macOS
.. code-block:: console
(venv) $ tox -e docs-lint
.. group-tab:: Linux
.. code-block:: console
(venv) $ tox -e docs-lint
.. group-tab:: Windows
.. code-block:: doscon
(venv) C:\...>tox -e docs-lint
This will validate the documentation does not contain:
* invalid syntax and markup
* dead hyperlinks
* misspelled words
If a valid spelling of a word is identified as misspelled, then add the word to
the list in ``docs/spelling_wordlist``. This will add the word to the
spellchecker's dictionary.
Rebuilding all documentation
----------------------------
To force a rebuild for all of the documentation:
.. tabs::
.. group-tab:: macOS
.. code-block:: console
(venv) $ tox -e docs-all
.. group-tab:: Linux
.. code-block:: console
(venv) $ tox -e docs-all
.. group-tab:: Windows
.. code-block:: doscon
(venv) C:\...>tox -e docs-all
The documentation should be fully rebuilt in the ``docs/_build/html`` folder.
If there are any markup problems, they'll raise an error.
|
