rust-lang / rust-lang/mdBook

Python preprocessor example is ignorant of part titles

Open Beginner friendly
#2,295 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-enhancement
Dominant language
Rust
Stars
22.2k
Forks
1.9k
PR merge metrics
PR metrics pending

Description

Problem

I am using mdBook in my Python libary project. The docs have a nice snippet of code for making a preprocessor in Python (thanks for that btw). However, I kept getting a KeyError saying that Chapter is not a valid key in the section. I couldn't even debug this since printing the output of the json would just be eaten by mdBook.

That is until today; instead of running print(book) I ran logging.error(book) which thankfully showed the entire json structure.

The reason for the KeyError was because the first entry was a part title.

Here's a small snippet of the JSON:

{
  "sections": [
      {"PartTitle": "User Guide"},
      {
          "Chapter": {
              "name": "Introduction",
              "content": "stuff",
              "number": [1],
              "sub_items": [],
              "path": "readme.md",
              "source_path": "readme.md",
              "parent_names": [],
          }
      },
      # more entries
  ]
}
Proposed Solution

The JSON structure should be mentioned along with the preprocessor snippet.

And this code just doesn't work unless you change the index.
https://github.com/rust-lang/mdBook/blob/01778fc90a8909ad8a51571816f2e236d0e13099/guide/src/for_developers/preprocessors.md?plain=1#L118-L119

Notes

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open guide/src/for_developers/preprocessors.md and inspect the preprocessor snippet around lines 118-119. Update the surrounding documentation to show that sections may begin with a PartTitle before a Chapter, correct the example's indexing, and ensure the JSON structure is explained clearly.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.