Skip to content

sphinx: add pdf generation #223

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

Draft
wants to merge 19 commits into
base: master
Choose a base branch
from
Draft

sphinx: add pdf generation #223

wants to merge 19 commits into from

Conversation

adamdebek
Copy link
Contributor

@adamdebek adamdebek commented Feb 12, 2025

JIRA: CI-526

Install latexmk, texlive-latex-extra to build latexpdf target.

@adamdebek adamdebek marked this pull request as draft February 12, 2025 15:54
@adamdebek adamdebek requested a review from damianloew February 12, 2025 16:11
@adamdebek adamdebek force-pushed the adamdebek/CI-526 branch 4 times, most recently from 17ce2e1 to 17b558d Compare February 17, 2025 18:18
@adamdebek adamdebek force-pushed the adamdebek/CI-526 branch 6 times, most recently from 6f46fe3 to 638453d Compare February 20, 2025 18:20
Copy link
Member

@mateusz-bloch mateusz-bloch left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this is a draft and may not be directly related to the purpose of this PR, but I noticed that changes are being made to the Building section.

The idea of separating the setup steps is definitely a good change. However, I’m not sure if the current naming makes sense. Linux page seems to refer more to the general environment setup required before building, which would be similar for macOS. The main difference would be in the commands used. Additionally, this setup is also relevant for Windows, considering that we primarily use WSL.

We might consider using something like sphinx-tabs for this purpose. As far as I know, sphinx-tabs should work with both .rst and .md, although the documentation examples focus on .rst. https://sphinx-tabs.readthedocs.io/en/latest/

Example:
image

Also, I would still mark all Ubuntu-specific commands as applicable to Ubuntu-based distributions.
Example:
image

In the future, we could extend this to other distributions, which sphinx-tabs could also be used for this purpose.

@damianloew

@adamdebek adamdebek force-pushed the adamdebek/CI-526 branch 2 times, most recently from 927cb3c to c8b1b92 Compare February 26, 2025 14:53
Copy link
Contributor

@damianloew damianloew left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some suggestion left based on our last call, nice to be added before merge

  • clickable links on the last page
  • parentheses in toolchaing building
  • improve the NOTE - now it looks like code
  • improve code blocks - align with text, change the font
  • change the declarations in libphoenix documentation from inline code blocks to code blocks
  • correct the first page to have a possibility to change text
  • Leave introduction in pdf (for now we can use this from the website)
  • fix html, for example:
    Screenshot from 2025-02-28 15-31-38

@adamdebek adamdebek force-pushed the adamdebek/CI-526 branch 2 times, most recently from 34f3d49 to a593fa5 Compare March 31, 2025 14:26
@adamdebek adamdebek force-pushed the adamdebek/CI-526 branch 2 times, most recently from 7439cb1 to 63a509d Compare April 10, 2025 16:04
@mateusz-bloch
Copy link
Member

Nitpicks:
consider adding the following to the README.md:

  • list of required dependencies that must be installed on the system
  • instructions on how to build the PDF

I know these might seem like obvious things, but it saves unnecessary googling for someone who hasn’t worked with this before


I also had an issue with this import not being found:

from version_management import get_version_context

Does it work correctly for you without any changes in the current PR?

@nalajcie
Copy link
Member

  • why there is a new PR [do not merge!] docs: add script to make documents with Phoenix-RTOS template #230 with mostly the same content?
  • please create separate PR (or multiple PRs) for changing the contents of the documentation
    • right now the amount of changes in this PR makes it impossible to review it
    • the changes to documentation contents are not directly related to this PR (they don't need the PDF generation to be merged)

Please try to keep the PR sizes reasonable - that way we can review/merge them faster.

@mateusz-bloch
Copy link
Member

This new PR is rebased onto the branch from the other PR to quickly generate PDF files, regardless of the source of the MD files. For now, it can be considered temporary, and its future depends on the final solution that will be agreed upon. Maybe I’ll just label it more clearly for now.

@adamdebek adamdebek force-pushed the adamdebek/CI-526 branch from 1531941 to 82ea89e Compare May 6, 2025 15:48
Copy link

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

markdownlint

[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD010/no-hard-tabs Hard tabs [Column: 1]


[markdownlint] reported by reviewdog 🐶
MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]

Copy link

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

markdownlint-fix

[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶


[markdownlint-fix] reported by reviewdog 🐶

adamdebek added 18 commits May 6, 2025 17:59
sphinx      7.2.6 -> 8.1.3
myst-parser 2.0.0 -> 4.0.1
furo        2024.1.29 -> 2024.8.6
pygments    2.17.2 -> 2.19.1

JIRA: CI-526
In Sphinx, the master document can be hidden. This was previously done because
it contained a table of contents, which was redundant—LaTeX automatically generates
its own table of contents when producing a PDF.

However, with the introduction of the :heading-level: argument to the rubric directive,
it's now possible to hide the table of contents specifically for LaTeX output without
affecting the HTML output. This makes it possible to display a brief system introduction
in the PDF without duplicating the table of contents.

JIRA: CI-526
@adamdebek adamdebek force-pushed the adamdebek/CI-526 branch from 82ea89e to 60c9057 Compare May 6, 2025 16:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants