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

Some documentation pages are unexpectedly blank #2483

Open
inetknght opened this issue Jul 13, 2022 · 8 comments
Open

Some documentation pages are unexpectedly blank #2483

inetknght opened this issue Jul 13, 2022 · 8 comments
Labels
Doc A documentation specific issue

Comments

@inetknght
Copy link
Contributor

Version of Beast

it seems all versions

Steps necessary to reproduce the problem

Small documentation issue.

Main documentation page [master, 1.78.0, 1.68.0] -> see "HTTP Examples" or "More Examples" with subitems. Click it.
HTTP Examples documentation page [master, 1.78.0, 1.68.0] -> empty page. I would expect the subitems on the previous page to be listed here

I did a small amount of digging. It looks like HTTP Examples page is generated from this QBK? I see the text These examples in this section are working functions that may be found in the examples directory. They demonstrate the usage of the library for a variety of scenarios. is there and additional text describing each sub item. But I am not familiar with QBK to diagnose why the page is empty.

It seems some other sections are similarly empty. The Concepts 1.78.0 page is similarly empty as is the 1.78.0 Configuration page. The 1.78.0 Quick Look page is empty -- but it at least links to the example directory listing even if it doesn't describe which examples do what.

Other sections appear to be correctly filled out. For example, the 1.78.0 WebSockets section has content.

It looks like the WebSocket section QBK mentions only a single section (with notes, headings, tables, includes, etc) and links to other sections while the HTTP Examples QBK has multiple sections.

@vinniefalco
Copy link
Member

The page is empty because its a new section I guess, press the "Next" button on that mostly blank page (the right arrow)

@sehe
Copy link
Collaborator

sehe commented Jul 13, 2022

The settings for section chunking with HTML output are in doc/Jamfile:

  <xsl:param>chunk.section.depth=8                # Depth to which sections should be chunked
  <xsl:param>chunk.first.sections=1               # Chunk the first top-level section?
  <xsl:param>toc.section.depth=8                  # How deep should recursive sections appear in the TOC?
  <xsl:param>toc.max.depth=8                      # How many levels should be created for each TOC?
  <xsl:param>generate.section.toc.level=8         # Control depth of TOC generation in sections

See also https://boostorg.github.io/quickbook/doc/html/boost_doc_tools/parameters.html

Changing to chunk.first.sections=0 is too invasive (and would e.g. lead to the quick reference appearing on the same page as the TOC).

Chunking (splitting to separate HTML pages) can be disabled locally:

[block'''<?dbhtml stop-chunking?>''']

Indeed including that leads to the first example appearing on the "more_examples.htm" page, while subsequent sections still appear on their own individual pages. I'd say we want to do this change:

image

@sehe
Copy link
Collaborator

sehe commented Jul 13, 2022

Mmm. Sadness:

  1. I was potentially too quick. Apparently the behaviour I described was only at partial rendered documentation, after completing the local rendering, all the "More HTTP Examples" appeared on a single page, which is not what we wanted
  2. The "Quick Start" (1_quick_look.qbk) appeared to have this stop-chunking directive but with a typo. "Fixing" the typo sadly shows the same behaviour of squashing all descendant sections to the single HMTL:
    _backup_cloudbackup_custom_ex_superboost_libs_beast_doc_html_beast_quick_start html(iPad Air)

The best I think we could do, then, is manually create some placeholder context on the main section page, perhaps with a bespoke hyperlink that duplicates what the "Next" button does in context...

@vinniefalco
Copy link
Member

Yeah its not perfect..

@alandefreitas
Copy link
Member

We tried to fix that before. I don't even remember in what library.

IIRC, the problem is we can't control the TOC depth for individual sections and the reference has subsections that look bad in the TOC.

If that's the case, the best solution would be to adapt docca to generate a document hierarchy that looks betters in the TOC.

@sehe
Copy link
Collaborator

sehe commented Jul 13, 2022 via email

@inetknght
Copy link
Contributor Author

Yes, I think it would be good enough to have a local TOC with the subitems from the parent page and a link back to the parent page.

As-is, if I copy the link from the main page and send it to a colleage, then the colleage could be lost because there's no information on the page linked and navigation by icons in the top right isn't clear (no text) and, when they opened the direct link, they can't just press the browser's back button to work from the parent page. So having the local TOC would help to navigate around the documentation.

@alandefreitas
Copy link
Member

Just as a reference, this is what happens when we remove the blank page:

image

@ashtum ashtum added the Doc A documentation specific issue label Jan 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Doc A documentation specific issue
Projects
None yet
Development

No branches or pull requests

5 participants