Metadata-Version: 2.5
Name: klink
Version: 0.1.12
Summary: A simple and clean Sphinx theme inspired by jrnl
Project-URL: Repository, https://github.com/pmorissette/klink
Project-URL: Homepage, https://pmorissette.github.io/klink/
Author-email: Philippe Morissette <morissette.philippe@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: sphinx>=7.3
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: bump-my-version; extra == 'dev'
Requires-Dist: check-dist; extra == 'dev'
Requires-Dist: codespell; extra == 'dev'
Requires-Dist: copier; extra == 'dev'
Requires-Dist: hatchling; extra == 'dev'
Requires-Dist: mdformat; extra == 'dev'
Requires-Dist: mdformat-tables>=1; extra == 'dev'
Requires-Dist: nbconvert; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff<0.17,>=0.16.5; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: ty; extra == 'dev'
Requires-Dist: uv; extra == 'dev'
Requires-Dist: wheel; extra == 'dev'
Provides-Extra: develop
Requires-Dist: build; extra == 'develop'
Requires-Dist: bump-my-version; extra == 'develop'
Requires-Dist: check-dist; extra == 'develop'
Requires-Dist: codespell; extra == 'develop'
Requires-Dist: copier; extra == 'develop'
Requires-Dist: hatchling; extra == 'develop'
Requires-Dist: mdformat; extra == 'develop'
Requires-Dist: mdformat-tables>=1; extra == 'develop'
Requires-Dist: nbconvert; extra == 'develop'
Requires-Dist: pytest; extra == 'develop'
Requires-Dist: pytest-cov; extra == 'develop'
Requires-Dist: ruff<0.17,>=0.16.5; extra == 'develop'
Requires-Dist: twine; extra == 'develop'
Requires-Dist: ty; extra == 'develop'
Requires-Dist: uv; extra == 'develop'
Requires-Dist: wheel; extra == 'develop'
Description-Content-Type: text/markdown

![image](http://pmorissette.github.io/klink/_static/logo.png)

[![image](https://github.com/pmorissette/klink/workflows/Build%20Status/badge.svg)](https://github.com/pmorissette/klink/actions/)

[![PyPI](https://img.shields.io/pypi/v/klink)](https://pypi.org/project/klink/)

[![PyPI - License](https://img.shields.io/pypi/l/klink)](https://pypi.org/project/klink/)

# klink - A Simple & Clean Sphinx Theme

Klink is a **simple** and **clean** theme for creating [Sphinx docs](http://sphinx-doc.org/). It is heavily inspired by the beautiful [jrnl theme](https://github.com/maebert/jrnl). It also supports embedding [IPython Notebooks](http://ipython.org/notebook.html) which can be mighty useful.

For a live demo, please visit [our docs](http://pmorissette.github.io/klink/).

## Options

Here are the theme options. They should be added to the html_theme_options in your **conf.py** file.

- **github**\
  The github address of the project. The format is name/project (pmorissette/klink).

- **logo**\
  The logo file. Assumed to be in the `_static` dir. Default is logo.png. The logo should be 150x150.

- **analytics_id**\
  Your Google Analytics id (usually starts with UA-...)

## IPython Notebook Integration

With the klink helper function **convert_notebooks()**, all notebooks will be converted to .rst so that they can be included in your docs. This includes all output including images. It’s a very convenient way to create Python docs!

All you have to do is create notebooks within your source directory (same directory as your conf.py file). Then, you add a call to klink.convert_notebooks() in your conf.py. You can also mix in **Markdown** cells or **Raw NBConvert** cells in your workbook. These will be converted to rst as well.

If you use the Raw NBConvert type cells, add a blank line at the start. There seems to be a bug in the rst conversion and if the cell does not begin with a blank line, you may run into some issues.

Using a Raw NBConvert cell with rst text inside is convenient, especially if you want to have links to other parts of your Sphinx docs.

## Installation

Assuming you have pip installed:

```sh
$ pip install klink
```

That's it.

## Usage

In your docs' **conf.py** file, add the following:

```python
html_theme = 'klink'
html_theme_options = {
    'github': 'yourname/yourrepo',
    'analytics_id': 'UA-your-number-here',
    'logo': 'logo.png'
}
```

Klink also comes with a useful helper function that allows you to integrate an IPython Notebook into a .rst file. It basically converts the Notebook to .rst and copies the static data (images, etc) to your `_static` dir.

If you have IPython Notebooks that you would like to integrate, use the following code to your **conf.py**:

```python
import klink

klink.convert_notebooks()
```

Once the conversion is done, you will have a .rst file with the same name as each one of your notebooks.

*NOTE: Place your notebooks in your docs' source dir.*

Now all you have to do is use the **include** command to insert them into your docs.

## Customization

Obviously, some of you will want to customize the theme. The easiest way to achieve this is to clone the repo into your `_themes` folder (create it if it does not exist in your docs' source dir). To change the style, I recommend editing the LESS files themselves. You will also need lessc to convert from less to css. See the css command in the Makefile for an example.

You may also want to explore the option of using **git subtree**. Here is a good [intro tutorial](http://makingsoftware.wordpress.com/2013/02/16/using-git-subtrees-for-repository-separation/).

You will also need to change your conf.py file. The following settings should work:

```
html_theme = 'klink'
html_theme_path = ['_themes']
html_theme_options = {
    'github': 'yourname/yourrepo',
    'analytics_id': 'UA-your-number-here',
    'logo': 'logo.png'
}
```

## Development

See [How to develop Klink](docs/development.md) for setup, checks, documentation builds, and template updates.
