Skip to content

Commit 0d811b9

Browse files
Marti Bolivarnashif
authored andcommitted
doc: overhaul getting_started
The getting started documentation has become a bit of a mess over time: - The reader needs to jump forward and backward in the documents depending on what their system already has installed (e.g. "start by cloning Zephyr, oh wait, see below if you don't have Git yet" etc.). - The operating system setup guides, toolchain setup instructions, and application build and run information have each become their own balkanized fiefdom, with duplicated, confusing and sometimes inconsistent results. - Linux documentation for all distributions is incomplete in some places (the Arch documentation in particular is vestigial) and wrong in others (platforms like Ubuntu still nominally require tools, like autoconf, that haven't been necessary since we stopped using the C Kconfig tools) - The dependencies needed to build the documentation have gotten *huge* since the LaTeX additions and massively overstate the footprint of Zephyr's real dependencies. This is particularly a problem on Linux, where those dependencies were not clearly separated from those needed to build Zephyr. - The toolchain setup documentation is confusing and scattered across the main file and the platform-specific files. There are various bits of incomplete and/or incorrect information. For example, the docs imply that you can use the Zephyr SDK on non-Linux hosts, which isn't true. As another example, some toolchains, such as GNU Arm Embedded, are documented several times. As a final example, some toolchains, such as Intel's ISSM, are squirrelled away in the Windows document when there are Linux builds available. Overhaul the pages to fix these issues and otherwise clean up the language. One significant side-effect is that all the toolchain-related information is rooted in a single toctree. Another is that it should now be possible to follow the instructions, in order, on any supported platform. Signed-off-by: Marti Bolivar <[email protected]>
1 parent 26e6162 commit 0d811b9

8 files changed

+629
-652
lines changed

doc/README.rst

Lines changed: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -55,10 +55,50 @@ Our documentation processing has been tested to run with:
5555
* sphinxcontrib-svg2pdfconverter version 0.1.0
5656
* Latexmk version version 4.56
5757

58-
In order to install the documentation tools, clone a copy of the git repository
59-
for the Zephyr project and set up your development environment as described in
60-
:ref:`getting_started`. This will ensure all the required tools are installed
61-
on your system.
58+
In order to install the documentation tools, first install Zephyr as
59+
described in :ref:`getting_started`. Then install additional tools
60+
that are only required to generate the documentation,
61+
as described below:
62+
63+
On Ubuntu Linux:
64+
65+
.. code-block:: console
66+
67+
sudo apt-get install --no-install-recommends doxygen librsvg2-bin \
68+
texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended
69+
70+
On Fedora Linux:
71+
72+
.. code-block:: console
73+
74+
sudo dnf install doxygen texlive-latex latexmk \
75+
texlive-collection-fontsrecommended librsvg2-tools
76+
77+
On Clear Linux:
78+
79+
.. code-block:: console
80+
81+
sudo swupd bundle-add texlive
82+
83+
On Arch Linux:
84+
85+
.. code-block:: console
86+
87+
sudo pacman -S doxygen librsvg texlive-core texlive-bin
88+
89+
On macOS:
90+
91+
.. code-block:: console
92+
93+
brew install doxygen mactex librsvg
94+
tlmgr install latexmk
95+
tlmgr install collection-fontsrecommended
96+
97+
On Windows in an Administrator ``cmd.exe`` prompt:
98+
99+
.. code-block:: console
100+
101+
choco install doxygen.install strawberryperl miktex rsvg-convert
62102
63103
.. note::
64104
On Windows, the Sphinx executable ``sphinx-build.exe`` is placed in

0 commit comments

Comments
 (0)