boostorg / boostorg/beast

Some documentation pages are unexpectedly blank

Open
#2,483 8 comments 0 reactions 0 assignees View on GitHub
Doc
Dominant language
C++
Stars
4.8k
Forks
694
Avg merge
12h 48m
Merged PRs (30d)
1

Description

### Version of Beast

it seems all versions

### Steps necessary to reproduce the problem

Small documentation issue.

Main documentation page [[master](https://www.boost.org/doc/libs/master/libs/beast/doc/html/index.html), [1.78.0](https://www.boost.org/doc/libs/1_78_0/libs/beast/doc/html/index.html), [1.68.0](https://www.boost.org/doc/libs/1_68_0/libs/beast/doc/html/index.html)] -> see "HTTP Examples" or "More Examples" with subitems. Click it.
HTTP Examples documentation page [[master](https://www.boost.org/doc/libs/master/libs/beast/doc/html/beast/more_examples.html), [1.78.0](https://www.boost.org/doc/libs/1_78_0/libs/beast/doc/html/beast/more_examples.html), [1.68.0](https://www.boost.org/doc/libs/1_68_0/libs/beast/doc/html/beast/more_examples.html)] -> 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](https://github.com/boostorg/beast/blob/b7344b0d501f23f763a76488826dde8c31f34b5d/doc/qbk/05_http_examples/_http_examples.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](https://www.boost.org/doc/libs/1_78_0/libs/beast/doc/html/beast/concepts.html) page is similarly empty as is the [1.78.0 Configuration](https://www.boost.org/doc/libs/1_78_0/libs/beast/doc/html/beast/config.html) page. The [1.78.0 Quick Look](https://www.boost.org/doc/libs/1_78_0/libs/beast/doc/html/beast/quick_start.html) 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](https://github.com/boostorg/beast/blob/b7344b0d501f23f763a76488826dde8c31f34b5d/doc/qbk/06_websocket/_websocket.qbk) 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.

Contributor guide

Open the contributing guide

Research direction

Start with doc/qbk/05_http_examples/_http_examples.qbk and compare its structure with the WebSocket section QBK linked in the report. Check how the generated HTTP Examples, Concepts, Configuration, and Quick Look pages handle their subsections. Done means the affected documentation pages render their expected text and subitems across the reported versions.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.