https://github.com/mkdocstrings/crystal

📘 Crystal language doc generator for https://github.com/mkdocstrings/mkdocstrings
https://github.com/mkdocstrings/crystal

crystal handler mkdocs mkdocstrings

Last synced: about 1 month ago
JSON representation

📘 Crystal language doc generator for https://github.com/mkdocstrings/mkdocstrings

• Host: GitHub
• URL: https://github.com/mkdocstrings/crystal
• Owner: mkdocstrings
• License: mit
• Created: 2020-10-13T20:07:35.000Z (about 4 years ago)
• Default Branch: master
• Last Pushed: 2024-02-11T18:52:45.000Z (9 months ago)
• Last Synced: 2024-09-30T22:14:27.396Z (about 1 month ago)
• Topics: crystal, handler, mkdocs, mkdocstrings
• Language: Python
• Homepage: https://mkdocstrings.github.io/crystal
• Size: 260 KB
• Stars: 28
• Watchers: 5
• Forks: 3
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE.md

Awesome Lists containing this project

README

        
# mkdocstrings-crystal

**[Crystal][] language doc generator for [MkDocs][], via [mkdocstrings][]**

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

[![License](https://img.shields.io/github/license/mkdocstrings/crystal)](https://github.com/mkdocstrings/crystal/blob/master/LICENSE.md)

[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mkdocstrings/crystal/ci.yml.svg)](https://github.com/mkdocstrings/crystal/actions?query=event%3Apush+branch%3Amaster)

## Introduction

*mkdocstrings-crystal* allows you to insert API documentation (generated from [Crystal][]'s source code and doc comments) as part of any page on a [MkDocs][] site.

[See it in action][showcase].

To install it, run (possibly in a [virtualenv][]):

```shell

pip install mkdocstrings-crystal

```

**Continue to the [documentation site][].**

## Usage

With [MkDocs][], add/merge this base config as your _mkdocs.yml_:

```yaml

site_name: My Project

theme:

  name: material

plugins:

  - search

  - mkdocstrings:

      default_handler: crystal

markdown_extensions:

  - pymdownx.highlight

  - deduplicate-toc

```

Then, in any `docs/**/*.md` file, you can **mention a Crystal identifier alone on a line, after `:::`**:

```md

::: MyClass

::: Other::Class#some_method

::: Foo::CONSTANT

```

-- and in the output this will be replaced with generated API documentation for it, much like Crystal's own doc generator does.

This, of course, happens as part of a normal MkDocs build process:

```shell

mkdocs build  # generate from docs/ into site/

mkdocs serve  # live preview

```

**Continue to the [documentation site][].**

[crystal]: https://crystal-lang.org/

[mkdocs]: https://www.mkdocs.org/

[mkdocstrings]: https://mkdocstrings.github.io/

[virtualenv]: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment

[documentation site]: https://mkdocstrings.github.io/crystal/

[showcase]: https://mkdocstrings.github.io/crystal/showcase.html