bookspine 0.1.0__tar.gz

bookspine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alkaid Cheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bookspine-0.1.0/LICENSES/Python-Markdown.txt

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright 2007, 2008 The Python Markdown Project (v. 1.7 and later)
+Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
+Copyright 2004 Manfred Stienstra (the original version)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

bookspine-0.1.0/LICENSES/pymdown-extensions.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 - 2025 Isaac Muse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bookspine-0.1.0/LICENSES/rust-crates.txt

@@ -0,0 +1,55 @@
+The compiled module bookspine._markdown contains the Rust standard library and
+the crates listed here. Each is offered under the MIT licence, alone or as one
+of several choices, and is used here under that licence, whose text follows the
+list.
+
+Rust standard library <https://github.com/rust-lang/rust>
+    Copyright (c) The Rust Project Contributors
+
+bitflags <https://github.com/bitflags/bitflags>
+    Copyright (c) 2014 The Rust Project Developers
+
+libc <https://github.com/rust-lang/libc>
+    Copyright (c) The Rust Project Developers
+
+memchr <https://github.com/BurntSushi/memchr>
+    Copyright (c) 2015 Andrew Gallant
+
+once_cell <https://github.com/matklad/once_cell>
+    The project's licence file names no copyright holder.
+
+portable-atomic <https://github.com/taiki-e/portable-atomic>
+    The project's licence file names no copyright holder.
+
+pulldown-cmark <https://github.com/pulldown-cmark/pulldown-cmark>
+    Copyright 2015 Google Inc. All rights reserved.
+
+pulldown-cmark-escape <https://github.com/pulldown-cmark/pulldown-cmark>
+    Copyright 2015 Google Inc. All rights reserved.
+
+pyo3 <https://github.com/PyO3/pyo3>
+    Copyright (c) 2023-present PyO3 Project and Contributors. https://github.com/PyO3
+
+pyo3-ffi <https://github.com/PyO3/pyo3>
+    Copyright (c) 2023-present PyO3 Project and Contributors. https://github.com/PyO3
+
+unicase <https://github.com/seanmonstar/unicase>
+    Copyright (c) 2014-2026 Sean McArthur
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

bookspine-0.1.0/PKG-INFO

@@ -0,0 +1,350 @@
+Metadata-Version: 2.4
+Name: bookspine
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Typing :: Typed
+Requires-Dist: jinja2
+Requires-Dist: pygments
+Requires-Dist: pyyaml
+Requires-Dist: black ; extra == 'dev'
+Requires-Dist: mypy ; extra == 'dev'
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: ruff ; extra == 'dev'
+Requires-Dist: types-pygments ; extra == 'dev'
+Requires-Dist: types-pyyaml ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+License-File: LICENSES/Python-Markdown.txt
+License-File: LICENSES/pymdown-extensions.txt
+License-File: LICENSES/rust-crates.txt
+Summary: Build a textbook-style static site from Markdown chapters.
+Keywords: documentation,markdown,static-site,textbook,mathjax
+Author-email: Alkaid Cheng <alkaidc@stanford.edu>
+License-Expression: MIT AND BSD-3-Clause
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/AlkaidCheng/bookspine
+Project-URL: Issues, https://github.com/AlkaidCheng/bookspine/issues
+Project-URL: Repository, https://github.com/AlkaidCheng/bookspine
+
+# bookspine
+
+bookspine turns a directory of Markdown chapters into a textbook-style static site,
+with numbered parts, chapters, sections, equations, figures, tables and boxed
+environments, citations, client-side search, and light and dark colour schemes. The
+theme comes with the package, so a book holds only its content and one configuration
+file.
+
+![The build reads book.yaml and the Markdown pages, converts them to HTML, numbers and resolves them, applies the theme and writes the site.](https://raw.githubusercontent.com/AlkaidCheng/bookspine/main/docs/pipeline.svg)
+
+| Step | What it does |
+|---|---|
+| Read | Reads `book.yaml` and the Markdown files it lists, in reading order. |
+| Convert | Turns each page's Markdown into HTML. |
+| Number | Numbers sections, figures, captioned tables, boxes and equations, resolves citations and links, and collects the search index. |
+| Theme | Puts each page into its template and gathers the static files. |
+| Write | Replaces what the last build wrote in `site/`. |
+
+The build stops on a broken internal link, a missing figure, a citation without a
+reference entry, an `\eqref` to a label no numbered equation carries, or an equation
+label used twice. A failed build leaves `site/` as it was.
+
+## Install
+
+```bash
+pip install bookspine
+```
+
+bookspine needs Python 3.11 or later and runs on Linux, macOS and Windows. pip installs a
+prebuilt wheel on x86-64 and ARM Linux with glibc 2.17 or later, on macOS with Apple silicon
+and on 64-bit Windows. Anywhere else it compiles the package, which needs a C compiler and,
+if Rust is not installed, downloads a copy of about 500 MB into the user cache.
+
+## Usage
+
+A book is a project directory:
+
+```text
+my-book/
+├── book.yaml             # title, author, parts and chapters
+├── book/
+│   ├── index.md          # the title page
+│   ├── help.md           # an optional help page
+│   └── methods/          # a part
+│       ├── index.md      # the part's opener
+│       ├── basics.md     # a chapter on one page
+│       └── figures/
+└── theme/                # optional overrides
+```
+
+Build it and preview the result:
+
+```bash
+bookspine build my-book
+python -m http.server --directory my-book/site 8000
+```
+
+Then open <http://127.0.0.1:8000/>.
+
+```text
+bookspine build [PROJECT_DIR] [--site-dir DIR] [--allow-warnings]
+```
+
+| Argument | Meaning |
+|---|---|
+| `PROJECT_DIR` | The directory holding `book.yaml`, by default the current one. |
+| `--site-dir DIR` | Where to write the site, by default `site/` in the project directory. |
+| `--allow-warnings` | Do not fail the build on warnings. A reference that is never cited is a warning. |
+
+`python -m bookspine` runs the same command. Each build lists any files under `theme/`
+that are in force.
+
+## Writing a book
+
+### Pages
+
+Pages follow [CommonMark](https://commonmark.org/), with tables, definition lists,
+footnotes and curly punctuation added, and every page starts with a YAML front matter
+block.
+
+| Key | Meaning |
+|---|---|
+| `title` | The page's title. Required. |
+| `summary` | One sentence, shown under the title and in the contents. |
+| `status` | For example `in-preparation`, which puts a badge in the contents and a notice on the page. |
+| `references` | Citation keys mapped to formatted entries, which may use Markdown. |
+
+Use `##` for sections and `###` for subsections; the build numbers them. An `##` named
+"References" or "Further reading", or carrying `{: .unnumbered }`, stays unnumbered.
+Section anchors come from the heading text, so renaming a heading changes its link.
+`{: #my-id }` after a heading pins its anchor.
+
+A page can also use these forms:
+
+| Form | Effect |
+|---|---|
+| `[^note]`, with `[^note]: Text` on a line of its own | A footnote, listed at the end of the page. Indent further paragraphs of the note by four spaces. |
+| `*[HTML]: HyperText Markup Language` on a line of its own | A tooltip on every `HTML` in the page. |
+| `++ctrl+alt+delete++` | Those keys, drawn as keycaps. A name that is not a key leaves the text as written. |
+| `{: .class #id key="value" }` on the line after a paragraph or list item | Those attributes on it. |
+
+### Parts and chapters
+
+`book.yaml` lists the parts and their chapters in reading order. Parts take Roman
+numerals, and chapters are numbered continuously through the book.
+
+```yaml
+parts:
+  - dir: methods
+    title: Methods
+    chapters:
+      - basics.md
+      - dir: inference
+        sections:
+          - likelihoods.md
+          - hypothesis-tests.md
+```
+
+`dir` is the part's directory under `book/`, which needs an `index.md`. A chapter is
+one Markdown file, or a `dir` with an `index.md` opener and one Markdown file per
+section. Each section page is numbered within the chapter (2.1, 2.2) and its `##`
+headings become subsections (2.1.1). Figures, tables, numbered boxes and equations keep
+one running count through a chapter, so splitting a chapter changes none of those
+numbers. Each page has its own `references` and reference list.
+
+### Figures and tables
+
+`![caption](figures/name.svg)` on a line of its own becomes a numbered figure. A local
+SVG is copied into the page, so it can use the theme's colours and follow the colour
+scheme. A table followed by a paragraph starting `Table:` becomes a numbered table, and
+a table with no caption takes no number. A button on each figure and table opens it
+enlarged.
+
+### Code
+
+A fenced code block takes the colours of the language named after its opening fence,
+which any of these options may follow:
+
+| Option | Effect |
+|---|---|
+| `title="app.py"` | A title above the block. |
+| `hl_lines="1 3-4"` | Marks those lines. |
+| `linenums="1"` | Numbers the lines, starting from that number. |
+
+Inline code takes a language's colours when it starts with `#!` and the language's name,
+as in `` `#!python x = 1` ``.
+
+### Equations
+
+Write inline math as `$…$` or `\(…\)`, and display math as `$$ … $$` on lines of their
+own. `\[…\]` or a `\begin{…}` environment that starts a paragraph is display math too.
+Every display equation is numbered, and `\notag` suppresses a number. `\label{eq:name}` and
+`\eqref{eq:name}` reach any page in the book, so a label must be unique across it.
+Place `\label` after `\end{aligned}` or `\end{split}`, because MathJax discards one
+written inside them. A page with no math does not load MathJax.
+
+### Citations
+
+`[@key]` cites an entry of the page's `references`, and `[@a; @b]` cites several. The
+reference list is generated at the end of the page, in order of first citation. A link
+that shows its own address, such as `<https://example.org/a/long/path>`, wraps between
+the address's elements with no hyphen added, so a long one fits a phone's screen.
+
+### Boxes
+
+`!!! kind "Title"` sets material apart, and `??? kind "Title"` makes it collapsible.
+
+| Kind | Effect |
+|---|---|
+| `definition`, `example`, `remark`, `recipe` | Numbered within the chapter, with a permalink. |
+| `warning`, `caution`, `note`, `tip` | Labelled, with no number. |
+| Any other, such as `summary` | Styled by its own name, with its title as written. |
+
+### Glossary
+
+A `\glossary` tag adds a reference to the book's glossary, which follows the last part
+with an opener, a page for terms and a page for equations. The tag prints nothing, as
+LaTeX's `\index` does. Each entry is a name that links to the place it marks, in
+alphabetical order. A page appears once it has an entry, so a book with no tags has no
+glossary.
+
+| Where | Tag | Entry |
+|---|---|---|
+| A paragraph or list item | `\glossary{Name}` | A term that links to this place. |
+| The start of a box | `\glossary` | A term named after the box's title, linking to the box. `\glossary{Name}` gives it another name. |
+| A display equation | `\glossary{Name}` | An equation of that name. It needs a `\label` and a number. |
+
+```markdown
+!!! definition "Jet"
+    \glossary
+    A collimated spray of hadrons.
+
+$$
+\sigma = \int f(x) \, \hat\sigma(x) \label{eq:xsec} \glossary{Factorisation formula}
+$$
+```
+
+The build stops on a name used twice on a page, and on a named equation with no label or
+number.
+
+### Help page
+
+A book can keep what a reader needs only now and then on a page of its own, such as its
+conventions, its notation, how to cite it and where to report a problem. `help_page` in
+`book.yaml` names a Markdown file in `book/`, and the foot of the sidebar links to it
+from every page, under the page's title. The page takes its address from the file's
+name, so `help.md` is served at `help/`, and the build stops if a part or the glossary
+holds that address. The page has no number, stays out of the contents and of the
+previous and next links, and is covered by the search.
+
+## Exporting
+
+Every table, figure, code block and display equation has a button that opens a menu of
+file formats. It appears when the cursor is over that component. On a touch screen it
+stays faintly visible, except on a code block, where a tap shows it. It sits at the end
+of a caption, at the top right of a code block or a table without a caption, and at the
+left of an equation. A code block also has a button that copies its source in one click.
+
+| Component | Formats |
+|---|---|
+| Table | Markdown, CSV, LaTeX, PNG, PDF |
+| SVG figure | SVG, PNG, PDF |
+| Other figure | PNG, PDF |
+| Code block | PNG, PDF |
+| Display equation | LaTeX, PNG, PDF |
+
+Exports use the light colour scheme on a white background. Markdown and LaTeX keep a
+table's caption, and images and PDFs leave it out. A code block keeps its source's
+lines, however it wraps on the page. Every format except PDF can also be
+copied to the clipboard. LaTeX output defines the book's macros it uses, and states the
+packages it needs.
+
+PDF opens the browser's print dialog with the page sized to the component, which keeps
+vectors and fonts: choose "Save as PDF" there. A browser that ignores the page size
+prints on its default paper.
+
+## Configuration
+
+`book.yaml` takes the keys below, and an unknown key stops the build.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `title`, `author` | required | The book's title and author. |
+| `subtitle`, `kicker` | empty | The lines around the title on the home page. |
+| `url` | empty | The published address. |
+| `repo` | empty | The source repository, linked from the sidebar. |
+| `repo_host` | empty | The name in that link, such as `GitHub`. Required with `repo`. |
+| `edit_url` | empty | The prefix of a page's edit link, followed by its path under `book/`. No link appears when it is empty. |
+| `help_page` | empty | The Markdown file in `book/` [linked from the foot of the sidebar](#help-page). |
+| `parts` | empty | The parts and chapters, as above. |
+| `enlarge_tables` | `true` | Whether a table has a button that opens it enlarged. Figures always do. |
+| `export_menus` | `true` | Whether tables, figures, code blocks and equations offer an [export menu](#exporting). |
+| `glossary` | `true` | Whether `\glossary` tags make [glossary](#glossary) pages. |
+| `wrap_code` | `true` | Whether a long line of code wraps, its continuation indented past the line's own indentation, instead of scrolling sideways. A block with line numbers always scrolls. |
+| `mathjax_macros` | empty | TeX macros, each a definition or `[definition, argument count]`. |
+| `pygments_light`, `pygments_dark` | `friendly`, `github-dark` | The [code colours](https://pygments.org/styles/) of each colour scheme. |
+
+```yaml
+title: A Book of Methods
+author: A. Author
+repo: https://github.com/example/methods
+repo_host: GitHub
+edit_url: https://github.com/example/methods/blob/main/book/
+mathjax_macros:
+  dd: \mathrm{d}
+  vec: ['\boldsymbol{#1}', 1]
+```
+
+## Overriding the theme
+
+A book changes the theme through its own `theme/` directory, which the build reads
+first.
+
+| Path | Effect |
+|---|---|
+| `theme/templates/NAME.html` | Replaces the package's template of that name. The templates are `base`, `home`, `part`, `chapter`, `section`, `glossary` and `help`. |
+| `theme/static/NAME` | Replaces the package's static file of that name, or adds a new one. A `pygments.css` here takes the place of the generated one. |
+
+A template replaced whole no longer receives changes from new releases, so extend the
+package's copy instead where a small change is enough. The package's templates stay
+reachable under `bookspine/`, and `base.html` has an empty `extra_head` block for
+additions to the page's head:
+
+```jinja
+{% extends "bookspine/base.html" %}
+{% block extra_head %}
+<link rel="stylesheet" href="{{ page.root }}static/local.css">
+{% endblock %}
+```
+
+## The site directory
+
+The build keeps a list of its top-level entries in `site/.bookspine-stamp.json`. A
+rebuild removes those entries whole and leaves any other top-level file alone. It stops
+if the directory is not empty and has no stamp, as it would for a mistyped `--site-dir`
+or a `site/` written by another program, and it refuses a filesystem root, the home
+directory, the project directory and anything holding them.
+
+## Revision dates
+
+The title page and footer show when the book was revised, by default the month of the
+build. A scheduled rebuild would advance that date with nothing changed, so set
+[`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/) to the
+last commit's time:
+
+```bash
+SOURCE_DATE_EPOCH=$(git log -1 --format=%ct) bookspine build
+```
+
+## License
+
+[MIT](https://github.com/AlkaidCheng/bookspine/blob/main/LICENSE)
+