Skip to content

Commit 8040546

Browse files
committed
Book: Add a sphinx preprocessor
This is to avoid having to use build_book.py script. 1. Preprocessor is faster and doesn't use disk, as all communication is trough stdio. 2. It doesn't need to be executed explicitly. You can just use `mdbook build docs` and it will create correct documentation. 3. New script is shorter and simpler than old. Script is based on example from https://rust-lang.github.io/mdBook/for_developers/preprocessors.html and uses a function from build_book.py In book.toml the command used is a simple bash script instead of just `python ./sphinx_preprocessor.py` because the command is run in the directory the user executed it in, not the directory that book.toml is in (which is imho a poor design in this case), so in order to be able to run the command both from main dir and from docs dir, such a script locating the preprocessor is necessary.
1 parent befa148 commit 8040546

File tree

2 files changed

+44
-1
lines changed

2 files changed

+44
-1
lines changed

docs/book.toml

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,13 @@ edition = "2021"
1111

1212
[output.html]
1313
default-theme = "ayu"
14-
git-repository-url = "https://github.com/scylladb/scylla-rust-driver"
14+
git-repository-url = "https://github.com/scylladb/scylla-rust-driver"
15+
16+
[preprocessor.sphinx]
17+
command = '''bash -c '
18+
if test -f "./docs/sphinx_preprocessor.py"; then
19+
python ./docs/sphinx_preprocessor.py "$@"
20+
else
21+
python ./sphinx_preprocessor.py "$@"
22+
fi' run_preprocessor
23+
'''

docs/sphinx_preprocessor.py

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import json
2+
import sys
3+
4+
def remove_sphinx_markdown(md_file_text):
5+
text_split = md_file_text.split("```eval_rst")
6+
7+
result = text_split[0]
8+
9+
for i in range(1, len(text_split)):
10+
cur_chunk = text_split[i]
11+
result += cur_chunk[cur_chunk.find("```") + 3:]
12+
13+
return result
14+
15+
def process_section(section):
16+
if 'Chapter' in section:
17+
section['Chapter']['content'] = remove_sphinx_markdown(section['Chapter']['content'])
18+
for s in section['Chapter']['sub_items']:
19+
process_section(s)
20+
21+
if __name__ == '__main__':
22+
if len(sys.argv) > 1: # we check if we received any argument
23+
if sys.argv[1] == "supports":
24+
# then we are good to return an exit status code of 0, since the other argument will just be the renderer's name
25+
sys.exit(0)
26+
27+
# load both the context and the book representations from stdin
28+
context, book = json.load(sys.stdin)
29+
30+
for section in book['sections']:
31+
process_section(section)
32+
33+
# we are done with the book's modification, we can just print it to stdout
34+
print(json.dumps(book))

0 commit comments

Comments
 (0)