Sphinx-multitoc-numbering

An extension for continuous numbering of toctree elements across multiple toctrees.

This package contains a Sphinx extension to continuously number sections across multiple toctrees. Also quite useful in jupyter-book projects for continuous numbering of chapters across different parts.

Warning

sphinx-multitoc-numbering is in an active development stage and may change rapidly.

Demo

Sphinx example

For the following rst code:

Part1

..  toctree::
    :numbered:

    Chap1
    Chap2

Part2

..  toctree::
    :numbered:

    Chap3

The resultant html numbering will look something like:

Part1

    1. Chap1 Title
    2. Chap2 Title

Part2

    3. Chap3 Title

Jupyter-book example

For the following code in _toc.yml:

- file: intro
  numbered: true

- part: part1
  chapters:
  - file: part1/chapter1
  - file: part1/chapter2

- part: part2
  chapters:
  - file: part2/chapter1

The resultant html numbering will look something like:

Intro

PART1

1. part1/chapter1 title
2. part1/chapter2 title

PART2

3. part2/chapter1 title

Inspiration

The development of sphinx-multitoc-numbering was mostly inspired from the discussions in this sphinx issue’s thread.

Getting Started

To get started with sphinx-multitoc-numbering, first clone the Github repo locally:

git clone https://github.com/executablebooks/sphinx-multitoc-numbering

and then install using the setup file

cd sphinx-multitoc-numbering
python setup.py install

Configuration

  1. Add this extension to the extensions list in your sphinx project’s conf.py:

        extensions = ["sphinx_multitoc_numbering"]
    
  2. Use the :numbered: option in toctrees if using Sphinx or numbered:true if using Jupyter Book,

Contributing Guide

Thank you for being interested in contributing to the sphinx-multitoc-numbering! Highly appreciated ✨.

This page contains information to help you get started with development on this project.

Development

Guidelines

For information about development conventions, practices, and infrastructure, please see the executablebooks/ development guidelines.

Set-up

Get the source code of this project using git:

git clone https://github.com/executablebooks/sphinx-multitoc-numbering
cd sphinx-multitoc-numbering

Install all the dependencies of this project, including packages for coding style and testing using:

pip install -e .[code_style,testing]

Unit Testing

We use pytest for testing, pytest-regression to regenerate expected outcomes of test and pytest-cov for checking coverage.

To simply run existing tests:

pytest

To run tests with coverage and an html coverage report:

pytest -v --cov=sphinxcontrib --cov-report=html

Coding Style

The consistency and code style in this project is enforced with multiple automated pre-commit hooks. You can install(recommend) and run them using:

pre-commit install
pre-commit run --all