DOC: Add outlines documentation and link it in User Guide

[mainuddin-md]

This adds documentation for reading and adding PDF outlines/bookmarks
as requested in issue #3484. Linked in User Guide.

[stefan6419846]

Thanks for the PR.

• Please have a look at the failing tests.
• Please move user docs to the user-specific directory.

[mainuddin-md]

Hi @stefan6419846 ,

I have resolved the failing tests and moved the user docs to the user-specific directory.

Please review.

[stefan6419846]

Could you please align this new guide with the other ones which have changed to execute the actual example code in the meantime?

[mainuddin-md]

Hi @stefan6419846,

Thanks for the feedback, I’ll align the new guide with the other ones that execute the actual example code and update the PR soon.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.31%. Comparing base (310e571) to head (79b48dc).
⚠️ Report is 43 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3511      +/-   ##
==========================================
+ Coverage   97.16%   97.31%   +0.15%     
==========================================
  Files          57       55       -2     
  Lines        9809     9769      -40     
  Branches     1781     1780       -1     
==========================================
- Hits         9531     9507      -24     
+ Misses        167      155      -12     
+ Partials      111      107       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mainuddin-md]

I have modified the PR to execute the actual code examples. Please review.

[stefan6419846]

Thanks for the update. Judging from the structure etc., it seems like this is mostly auto-generated using AI - which is no issue as long as you have checked the changes yourself and it follows our usual structure.

Unfortunately, I cannot merge this as-is:

• Could we please use subsections instead of separate files for reading and writing?
• Why is the introduction a note in one case, but regular text in the other. I guess we should make this regular text.
• The user docs are not for resembling the exact API and describing the parameters. These should go into the docstrings. If required, link to the corresponding methods/classes in your description using the corresponding Sphinx directive/role.
• Please do not save arbitrary (and large) files in the resources directory. If you keep the order "Add" - "Read", you should be able to re-use the generated file in the second examples.
• Do not import from internal modules like _fit. Use the public API only!
• Instead of creating a reader and writer and adding the pages manually, just use writer = PdfWriter(clone_from="input.pdf").
• The description of what the code does usually goes before it. This should be no list, but a short descriptive text.
• If you decide to include screenshots, please make sure that they ideally resemble the input document and you have the necessary rights to include it. If highlighting is required, use proper drawing tools to get nice rectangles instead of arbitrary drawings.

Please note that I might have missed some aspects during this review due to merging this requires some larger changes anyway.

[mainuddin-md]

Hi @stefan6419846, I have incorporated the changes you suggested. requesting for review again. Thank you

[stefan6419846]

• This file is rather large. Can we use a smaller one - or even one of the existing?
• Do you own all the necessary copyrights to actually distribute this?

[mainuddin-md]

I have reduced the pdf file size and I have all necessary copyrights because I had createad it by myself using google docs.

[stefan6419846]

I am still not fully convinced why we cannot use one of the existing files? Especially since input.pdf is rather generic and we try to keep the changes to the resources directory as small as possible.

[stefan6419846]

I am still not fully convinced why we cannot use one of the existing files? Especially since input.pdf is rather generic and we try to keep the changes to the resources directory as small as possible.

[mainuddin-md]

Hi @stefan6419846,

Thanks for the feedback. we need to upload output.pdf (a new pdf file which contains all the outlines) to the resources folder to ensure the reading tests pass. Since we are using a testoutput block to verify the outlines, the test runner needs a physical file to read from, which is why I included it.

Please review. Thank you

[stefan6419846]

Since we are using a testoutput block to verify the outlines, the test runner needs a physical file to read from, which is why I included it.

The process in the docs adds the outlines, thus reading the output from the previous step in the next step should still work, without having to add an output.pdf file to the repository explicitly?

[mainuddin-md]

Since we are using a testoutput block to verify the outlines, the test runner needs a physical file to read from, which is why I included it.

The process in the docs adds the outlines, thus reading the output from the previous step in the next step should still work, without having to add an output.pdf file to the repository explicitly?

Hi @stefan6419846,
I removed this output.pdf file and reading the output from the perivous steps.

However, to make the reading section work properly without overwriting, I'm saving each write code example section namely simple, nested and advanced in separate files namely simple-example.pdf , nested-example.pdf and advanced-example.pdf. Since, you gave the review comment to keep only one screenshot for all examples, the screenshot will not be completly in line with the code written to save output in different files.

Please review, Thank you.

[stefan6419846]

Thanks for your patience.