This is an automated email from the ASF dual-hosted git repository.
janc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mynewt-documentation.git
The following commit(s) were added to refs/heads/master by this push:
new 5255ec7 README: Add instructions for building PDF documentation
5255ec7 is described below
commit 5255ec79440c3403136ca8a0ae2185aa3b4bf675
Author: Wojciech Pietraszewski <[email protected]>
AuthorDate: Fri Sep 27 17:46:31 2024 +0200
README: Add instructions for building PDF documentation
Adds information on setting up the environment for
generating PDF documentation.
---
README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 53 insertions(+)
diff --git a/README.md b/README.md
index 6ac9c4a..ff77852 100644
--- a/README.md
+++ b/README.md
@@ -133,3 +133,56 @@ To preview the changes:
cd mynewt-documentation/versions/vX_Y_Z/mynewt-documentation
make clean && make docs && (cd _build/html && python -m SimpleHTTPServer 8080)
```
+
+## Generating PDF File
+
+### Apply the Workaround
+
+Due to a potential issue with Sphinx's PDF builder, there is an additional
step
+that needs to be performed on each dependent repository before building the
documentation.
+The issue is related to Sphinx's `.. toctree::` directive.
+The output (PDF only) renders some sections in incorrect order when there is
content in `index.rst`
+files used to chain source `RST` files together.
+
+The workaround is to manually alter the affected files, so that there is no
content but the
+toctree directive in those `index.rst` files.
+
+First, fetch the `sphinx-workaround` branch for one of the repositories:
+
+```bash
+git fetch https://github.com/wpiet/mynewt-documentation sphinx-workaround
+git checkout -b sphinx-workaround FETCH_HEAD
+```
+
+Then, rebase onto the downloaded branch:
+
+```bash
+git checkout master
+git rebase sphinx-workaround
+```
+
+Repeat the above steps for all dependent repositories, changing the `git
fetch` command accordingly:
+```bash
+git fetch https://github.com/wpiet/mynewt-core sphinx-workaround
+git fetch https://github.com/wpiet/mynewt-nimble sphinx-workaround
+git fetch https://github.com/wpiet/mynewt-newt sphinx-workaround
+git fetch https://github.com/wpiet/mynewt-newtmgr sphinx-workaround
+```
+
+### Build the Docs
+
+In the `mynewt-site` directory run:
+
+```shell
+./build.py
+```
+
+In the `mynewt-documentation` run:
+
+```shell
+make latexpdf
+```
+
+This will generate the PDF file (for the version set as the `latest` in
`mkdocs.yml`) in
+the following path:
+`_build/latex/Mynewt.pdf`
