Documentation: pdf build of documentation

[hkershaw-brown]

What's the issue?

📚 Please describe the problem you’ve noticed in the documentation.

Had a request for pdf version of the DART documentation. Not currently building pdf or epub.

Here is the current (v11.15) pdf version (see main...rtd-pdf for the conf.py change to switch this on).
https://docs.dart.ucar.edu/_/downloads/en/rtd-pdf/pdf/

Where did you find the issue?

Provide the location(s) of the issue:

It is the contents/toc/chapter heading:

Sections in index.rst are chapters, then everything else (~1000 pages) is under the references. Here is the start and end of the table of contents:

.
.
.  
.
.

What needs to be fixed?

Share what’s incorrect, unclear, missing, or outdated.

• Organization of documentation
• There are some (many?) links that are hardcoded to the html, so break in the pdf, e.g. the link will go to:
  https://docs.dart.ucar.edu/_/downloads/en/filter/filter.html#DetailedProgramFlow
  which does not exist.
• various image formats don't work out of the box (gif, svn)
• The links to the dart tutorial do not work
• Some of the tables go off the page.

Also my sanity after setting up local build of latex pdf for readthedocs on mac.

Suggestions for improvement

I'm not sure of the demand for pdf/epub for the dart docs, but I think the organizing the current documentation for navigation is a worthwhile exercise.

Anything else we should know?

Include any other relevant details, such as references, screenshots, or related discussions.

[hkershaw-brown]

the ebup uses the rtd side bar, so looks better at least in apple books:

[dtembo1]

Hello @hkershaw-brown, I'm interested in contributing to issue #977 and would appreciate it if you could assign it to me. I've reviewed the u=issue and think I can help find a solution. Let me know if that's okay with you.
Thanks!

@dtembo1

[hkershaw-brown]

Hi @dtembo1, yes for sure. I've assigned you the issue.

We have a small contributors guide, please take a read through:
https://docs.dart.ucar.edu/en/latest/guide/contributors-guide.html

Note, for this issue it would be great to fix the build problems -the contents page, the links, the format. A rewite/reorganization of the docs would be beyond the scope of this issue, mostly because it will take a lot of review if there are large scale changes and less likely that we will be able to merge your pull request.

Let me know if you have questions.
Cheers,
Helen

[dtembo1]

Hi @hkershaw-brown ,

Thanks for assigning me the issue and sharing the contributor's guide I'll definitely go through it carefully.

Got it on the scope; I’ll focus on fixing the build issues, including the contents page, links, and formatting, without making broader structural changes. I’ll reach out if I have any questions along the way.

Looking forward to contributing!

Best,
Dalitso