Piccolo Theme

A clean and modern theme for Sphinx.

Setup

Install Sphinx

pip install sphinx

Create a docs folder within your project, and run sphinx-quickstart.

mkdir docs
cd docs
sphinx-quickstart

sphinx-quickstart will scaffold your documentation for you.

Install Piccolo Theme

pip install piccolo_theme

Find the conf.py file that Sphinx generated for you. Within that set the following value:

html_theme = 'piccolo_theme'

Building your docs

Sphinx creates a Makefile in your docs folder. To generate some HTML docs, run the following in the same directory as your Makefile:

make html

Within your docs folder, Sphinx will have generated some HTML files in _build/html.

To serve these files using Python, you can use:

python -m http.server --directory _build/html/

Now open up http://localhost:8000 in your browser to see your beautiful docs!

Configuration

html_short_title

If you have a really long project name, you may prefer something shorter to appear in the navigation bar. Specify this using html_short_title in conf.py:

# conf.py

# By default the project value is used in the nav bar.
project = 'My Extra Special Amazing Docs'

# If specified, this will be used in the nav bar instead.
html_short_title = "Amazing Docs"

Help

The best place to get help is on our GitHub discussions page.

It’s also a great place to share any feedback you have about the theme, and how we can make improvements.

Support Us

You can help us in many ways:

  • Sharing the project with others

  • Leaving feedback

  • Starring the repo on GitHub

  • Making improvements to the theme by making a pull request

Thanks! 🙏

About

This theme was created to document Piccolo and sister projects.

Here’s a live example of it being used:

Contributing

Styles

We use Sass as a CSS preprocessor. The styles live in src/sass.

To modify the styles, first install Sass:

npm install -g sass

Then run:

./scripts/build-styles.sh

This will automatically rebuild your CSS when it detects a change in the Sass files.

Running the docs

By running Piccolo Theme’s docs you can verify that your changes look OK.

First install the requirements:

pip install -r requirements/doc-requirements.txt

Then launch a web server using the following script:

./scripts/run-docs.sh

It auto reloads when it detects changes to the documentation or theme files.

Demo

This is used to demonstrate various features, and also for testing.

Autodoc

class piccolo_theme.snippets.Column(null: bool = False, primary_key: bool = False, unique: bool = False, index: bool = False, required: bool = False, help_text: Optional[str] = None, choices: Optional[Type[enum.Enum]] = None, db_column_name: Optional[str] = None, secret: bool = False, **kwargs)

All other columns inherit from Column. Don’t use it directly.

The following arguments apply to all column types:

Parameters

  • null – Whether the column is nullable.

  • primary_key – If set, the column is used as a primary key.

  • default – The column value to use if not specified by the user.

  • unique – If set, a unique contraint will be added to the column.

  • index – Whether an index is created for the column, which can improve the speed of selects, but can slow down inserts.

  • index_method – If index is set to True, this specifies what type of index is created.

  • required – This isn’t used by the database - it’s to indicate to other tools that the user must provide this value. Example uses are in serialisers for API endpoints, and form fields.

  • help_text – This provides some context about what the column is being used for. For example, for a Decimal column called value, it could say 'The units are millions of dollars'. The database doesn’t use this value, but tools such as Piccolo Admin use it to show a tooltip in the GUI.

  • choices – An optional Enum - when specified, other tools such as Piccolo Admin will render the available options in the GUI.

  • db_column_name –

    If specified, you can override the name used for the column in the database. The main reason for this is when using a legacy database, with a problematic column name (for example 'class', which is a reserved Python keyword). Here’s an example:

    class MyTable(Table):
    class_ = Varchar(db_column_name="class")

>>> await MyTable.select(MyTable.class_)
[{'id': 1, 'class': 'test'}]

    This is an advanced feature which you should only need in niche situations.

  • secret –

    If secret=True is specified, it allows a user to automatically omit any fields when doing a select query, to help prevent inadvertent leakage of sensitive data.

    class Band(Table):
    name = Varchar()
    net_worth = Integer(secret=True)

>>> await Band.select(exclude_secrets=True)
[{'name': 'Pythonistas'}]

Breathe

class CppClass

CppClass class.

Details about CppClass.

Public Functions

const char *member_function(char, int)

A member function.

Parameters

  • c – a character.

  • n – an integer.

Throws

std::out_of_range – parameter is out of range.

Returns

a character pointer.

void cpp_function(int *a, int *b, int *c)

Doing important things with parameter directions.

Parameters

  • a – [out] output

  • b – [in] input

  • c – [inout] input but gets rewritten

Tables

Table 1

Name

Drives

Alice

True

Bob

True

Curtis

False

Table 2

Header 1

Header 2

Header 3

body row 1

column 2

column 3

body row 2

Cells may span columns.

And several paragraphs.

body row 3

Cells may span rows.

  • Cells

  • contain

  • blocks.

body row 4

Data definitions

Python

A great programming language.

Sphinx

A powerful documentation tool.

Lists

Unordered List

  • Python

  • Rust

  • Javascript

Ordered List

  1. Python

  2. Rust

  3. Javascript

Admonitions

Warning

This is a warning!

Error

This is an error!

Hint

This is a hint!

Note

This is a note!

Changes

0.6.0

If html_short_title is in conf.py then this is used in the nav bar instead of the full project title.

0.5.1

Fixed dark mode styles - some elements weren’t visible. Thanks to @alorence for reporting this issue.

0.5.0

Added table styles.

0.4.0

Improved the appearance of autodoc output for C++ files (when using breathe). Courtesy @thijsmie.

0.3.0

Added dark mode.

0.2.5

Improved search styles.

0.2.4

Added missing requirements.txt file to manifest. Thanks to @moorepants for reporting this.

0.2.3

Make the page contents text smaller when the right hand sidebar is hidden.

0.2.2

Fix missing static files.

0.2.1

Fix missing static files.

0.2.0

Improved the main header on mobile - the search bar is replaced with a search icon. Also increased the size of the touch targets for showing / hiding the right sidebar, for easier use on mobile. See PR 7.