Skip to content

Commit

Permalink
README: Add instructions for building PDF documentation
Browse files Browse the repository at this point in the history
Adds information on setting up the environment for
generating PDF documentation.
  • Loading branch information
wpiet committed Sep 27, 2024
1 parent 79cf826 commit 286f5e4
Showing 1 changed file with 43 additions and 0 deletions.
43 changes: 43 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,3 +133,46 @@ 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 each of the repos:
```bash
git fetch https://github.com/wpiet/mynewt-core sphinx-workaround
git checkout -b sphinx-workaround FETCH_HEAD
```

Then, rebase onto this branch:

```bash
git checkout master
git rebase sphinx-workaround
```

Repeat the above steps for all dependent repositories.


### Build the Docs

In the `mynewt-site` directory run:

```shell
./build.py
```

In the `mynewt-documentation` run:

```shell
make latexpdf
```

0 comments on commit 286f5e4

Please sign in to comment.