Skip to content

Commit

Permalink
move PDF content down (less important) IQSS#10531
Browse files Browse the repository at this point in the history
  • Loading branch information
pdurbin committed Jun 13, 2024
1 parent d92cb68 commit 6b3d06c
Showing 1 changed file with 19 additions and 18 deletions.
37 changes: 19 additions & 18 deletions doc/sphinx-guides/source/contributor/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,24 +111,6 @@ After Sphinx is done processing the files you should notice that the `html` fold

Now you can make a commit with the changes to your own fork in GitHub and submit a pull request. See {ref}`how-to-make-a-pull-request`.

## PDF Version of the Guides

The HTML version of the guides is the official one. Any other formats are maintained on a best effort basis.

If you would like to build a PDF version of the guides and have Docker installed, please try the command below from the root of the git repo:

`docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx-latexpdf:3.5.4 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make latexpdf LATEXMKOPTS=\"-interaction=nonstopmode\"; cd ../.. && ls -1 doc/sphinx-guides/build/latex/Dataverse.pdf"`

A few notes about the command above:

- Hopefully the PDF was created at `doc/sphinx-guides/build/latex/Dataverse.pdf`.
- For now, we are using "nonstopmode" but this masks some errors.
- See requirements.txt for a note regarding the version of Sphinx we are using.

Also, as of this writing we have enabled PDF builds from the "develop" branch. You download the PDF from <http://preview.guides.gdcc.io/_/downloads/en/develop/pdf/>

If you would like to help improve the PDF version of the guides, please get in touch! Please see {ref}`getting-help-developers` for ways to contact the developer community.

## Writing Guidelines

### Writing Style Guidelines
Expand Down Expand Up @@ -169,6 +151,25 @@ TODO: The above covers "how" but what about "when"?

When adding ReStructured Text (.rst) [cross references](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role), use the hyphen character (`-`) as the word separator for the cross reference label. For example, `my-reference-label` would be the preferred label for a cross reference as opposed to, for example, `my_reference_label`.

## PDF Version of the Guides

The HTML version of the guides is the official one. Any other formats are maintained on a best effort basis.

If you would like to build a PDF version of the guides and have Docker installed, please try the command below from the root of the git repo:

`docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx-latexpdf:3.5.4 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make latexpdf LATEXMKOPTS=\"-interaction=nonstopmode\"; cd ../.. && ls -1 doc/sphinx-guides/build/latex/Dataverse.pdf"`

A few notes about the command above:

- Hopefully the PDF was created at `doc/sphinx-guides/build/latex/Dataverse.pdf`.
- For now, we are using "nonstopmode" but this masks some errors.
- See requirements.txt for a note regarding the version of Sphinx we are using.

Also, as of this writing we have enabled PDF builds from the "develop" branch. You download the PDF from <http://preview.guides.gdcc.io/_/downloads/en/develop/pdf/>

If you would like to help improve the PDF version of the guides, please get in touch! Please see {ref}`getting-help-developers` for ways to contact the developer community.


## Hosting Your Own Version of the Guides

Some installations of Dataverse maintain their own versions of the guides and use settings like {ref}`:NavbarGuidesUrl` or {ref}`:GuidesBaseUrl` to point their users to them.
Expand Down

0 comments on commit 6b3d06c

Please sign in to comment.