Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PDF export strategy for user documentation #6

Open
aputtu opened this issue Oct 31, 2023 · 1 comment
Open

PDF export strategy for user documentation #6

aputtu opened this issue Oct 31, 2023 · 1 comment
Assignees
Labels
documentation Improvements or additions to documentation question Further information is requested

Comments

@aputtu
Copy link
Contributor

aputtu commented Oct 31, 2023

Ideally, we want simple, topic specific user documentation guides in PDF format, so that we can refer user to these for their convenience.

Sphinx has the option for multiple PDFs, but does Read the Docs?
Sphinx allows for export of multiple PDF files from our restructured text. so that we can have:

  • ERDA PDF guide - own logo
  • SIF PDF guide - own logo
  • Specific PDF guides, e.g. "FileZilla on Linux".

However, it seems like Read the Docs blocks for Sphinx's build options - and even if a solution exists, it hasn't been put into production:
readthedocs/readthedocs.org#2045

We have a few options:

  1. Maintain multiple user documentation guides through multiple Read the Docs projects. Simply use primary PDF export without much configuration.
    Pro: This will give us the PDF guides needed.
    Con: complexity in maintenance.
  2. Dive into how to make PDF export work, regardless of Read the Docs. We should be able to create them using the Sphinx configurations. Alternatively, Read the Docs might have a solution already - worth finding out.
    Pro: Unified editing and maintenance is preferable.
    Con: Time investigating further. We might need to refer to unofficial sources, and keep track of breaking changes.
  3. Abandon the concept of separate, topic specific PDF guides for the time being.
    Pro: "It's good enough." Read the Docs offers a responsive design and search functionality. Unified maintenance.
    Con: Users benefiting from a simple, topic specific PDF guide could be overwhelmed by the documentation.

It almost goes without saying, that choosing option 1 will require us to split user documentation sections.

@aputtu aputtu added documentation Improvements or additions to documentation question Further information is requested labels Oct 31, 2023
@SebastianPrehn
Copy link
Contributor

Personally,. I prefer solution 2. or 3., where we just convert it into one big PDF and use external tools to separate them into our desired PDFs to offer them elsewhere as an acceptable solution.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation question Further information is requested
Projects
None yet
Development

No branches or pull requests

2 participants