diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml index d476929923..7fed7200e4 100644 --- a/.github/workflows/book.yml +++ b/.github/workflows/book.yml @@ -33,7 +33,5 @@ jobs: run: cargo build --verbose --examples - name: Build the book run: mdbook build docs - - name: Build the book using the script - run: python3 docs/build_book.py - name: Run book tests run: mdbook test -L target/debug/deps docs diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fd2debba32..174c11cb8b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,17 +72,20 @@ But they are removed when building the book cargo install mdbook ``` -Build the book (simple method, contains `Sphinx` artifacts): +Book build process uses preprocessor to remove Sphinx artifacts. +Due to limitation of mdbook, it can only be built either from main directory, +using `mdbook X docs` or from `docs` directory, using `mdbook X`, where +`X` is mdbook command such as `build` / `serve` / `test` etc. + +If the book is built from another directory (e.g. scylla, using `mdbook build ../docs`), +preprocessor won't be found, so the result will contain Sphinx artifacts. + +Build the book. ```bash mdbook build docs # HTML will be in docs/book ``` -To build the release version use a script which automatically removes `Sphinx` chunks: -```bash -python3 docs/build_book.py -# HTML will be in docs/book/scriptbuild/book -``` Or serve it on a local http server (automatically refreshes on changes) ```bash diff --git a/Makefile b/Makefile index 72396cd0a7..e09ee6bc60 100644 --- a/Makefile +++ b/Makefile @@ -46,7 +46,7 @@ build: .PHONY: docs docs: - ./docs/build_book.py + mdbook build docs .PHONY: up up: diff --git a/docs/book.toml b/docs/book.toml index 91309c263f..f1726787a9 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -11,4 +11,13 @@ edition = "2021" [output.html] default-theme = "ayu" -git-repository-url = "https://github.com/scylladb/scylla-rust-driver" \ No newline at end of file +git-repository-url = "https://github.com/scylladb/scylla-rust-driver" + +[preprocessor.sphinx] +command = '''bash -c ' +if test -f "./docs/sphinx_preprocessor.py"; then + python ./docs/sphinx_preprocessor.py "$@" +else + python ./sphinx_preprocessor.py "$@" +fi' run_preprocessor +''' diff --git a/docs/build_book.py b/docs/build_book.py deleted file mode 100755 index 726f33a8d3..0000000000 --- a/docs/build_book.py +++ /dev/null @@ -1,66 +0,0 @@ -#!/usr/bin/env python3 - -# A script which removes sphinx markdown and builds the documentation book -# It copies all files to working directory, modifies the .md files -# to remove all ```eval_rst parts and builds the book -# The generated HTML will be in docs/book/scriptbuild/book - -import os -import shutil -import pathlib - -def remove_sphinx_markdown(md_file_text): - text_split = md_file_text.split("```eval_rst") - - result = text_split[0] - - for i in range(1, len(text_split)): - cur_chunk = text_split[i] - result += cur_chunk[cur_chunk.find("```") + 3:] - - return result - -# Working directory, normally book builds in docs/book -# so we can make our a folder in this build directory -work_dir = os.path.join("docs", "book", "scriptbuild") -os.makedirs(work_dir, exist_ok = True) - -# All modified sources will be put in work_dir/source -src_dir = os.path.join(work_dir, "source") -os.makedirs(src_dir, exist_ok = True) - -# Generated HTML will be put in work_dir/book -build_dir = os.path.join(work_dir, "book") - - - -# Copy all mdbook files to work_dir before modifying - -# Copy book.toml -shutil.copyfile(os.path.join("docs", "book.toml"), os.path.join(work_dir, "book.toml")) - -# Go over all .md files, remove the ``` sphinx parts and put them in work_dir/source -for mdfile_path in pathlib.Path(os.path.join("docs", "source")).rglob("*.md"): - - # Path in the book structure ex. queries/queries.md instead of docs/source/queries/queries.md - relative_path = mdfile_path.relative_to(os.path.join("docs", "source")) - - # Read the current file - mdfile = open(mdfile_path, "r").read() - - # Remove sphinx markdown - new_mdfile = remove_sphinx_markdown(mdfile) - - # Write the modified file to src_dir - new_mdfile_path = os.path.join(src_dir, relative_path) - os.makedirs(os.path.dirname(new_mdfile_path), exist_ok = True) - open(new_mdfile_path, "w").write(new_mdfile) - -build_result = os.system(f"mdbook build {work_dir}") - -if build_result == 0: - print(f"OK Done - rendered HTML is in {build_dir}") - exit(0) -else: - print(f"ERROR: mdbook build returned: {build_result}") - exit(1) diff --git a/docs/sphinx_preprocessor.py b/docs/sphinx_preprocessor.py new file mode 100644 index 0000000000..fc85848e11 --- /dev/null +++ b/docs/sphinx_preprocessor.py @@ -0,0 +1,34 @@ +import json +import sys + +def remove_sphinx_markdown(md_file_text): + text_split = md_file_text.split("```eval_rst") + + result = text_split[0] + + for i in range(1, len(text_split)): + cur_chunk = text_split[i] + result += cur_chunk[cur_chunk.find("```") + 3:] + + return result + +def process_section(section): + if 'Chapter' in section: + section['Chapter']['content'] = remove_sphinx_markdown(section['Chapter']['content']) + for s in section['Chapter']['sub_items']: + process_section(s) + +if __name__ == '__main__': + if len(sys.argv) > 1: # we check if we received any argument + if sys.argv[1] == "supports": + # then we are good to return an exit status code of 0, since the other argument will just be the renderer's name + sys.exit(0) + + # load both the context and the book representations from stdin + context, book = json.load(sys.stdin) + + for section in book['sections']: + process_section(section) + + # we are done with the book's modification, we can just print it to stdout + print(json.dumps(book))