| Name | quartodoc JSON |
| Version |
0.7.6
JSON |
| download |
| home_page | None |
| Summary | Generate API documentation with Quarto. |
| upload_time | 2024-08-22 20:10:38 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License Copyright (c) 2023 quartodoc authors 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. |
| keywords |
documentation
quarto
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Overview
[](https://github.com/machow/quartodoc/actions/workflows/ci.yml)
**quartodoc** lets you quickly generate Python package API reference
documentation using Markdown and [Quarto](https://quarto.org). quartodoc
is designed as an alternative to
[Sphinx](https://www.sphinx-doc.org/en/master/).
Check out the below screencast for a walkthrough of creating a
documentation site, or read on for instructions.
<p align="center">
<a href="https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed">
<img src="https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif" width="75%">
</a>
</p>
<br>
## Installation
``` bash
python -m pip install quartodoc
```
or from GitHub
``` bash
python -m pip install git+https://github.com/machow/quartodoc.git
```
<div>
> **Install Quarto**
>
> If you haven’t already, you’ll need to [install
> Quarto](https://quarto.org/docs/get-started/) before you can use
> quartodoc.
</div>
## Basic use
Getting started with quartodoc takes two steps: configuring quartodoc,
then generating documentation pages for your library.
You can configure quartodoc alongside the rest of your Quarto site in
the
[`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html)
file you are already using for Quarto. To [configure
quartodoc](https://machow.github.io/quartodoc/get-started/basic-docs.html#site-configuration),
you need to add a `quartodoc` section to the top level your
`_quarto.yml` file. Below is a minimal example of a configuration that
documents the `quartodoc` package:
``` yaml
project:
type: website
# tell quarto to read the generated sidebar
metadata-files:
- _sidebar.yml
quartodoc:
# the name used to import the package you want to create reference docs for
package: quartodoc
# write sidebar data to this file
sidebar: _sidebar.yml
sections:
- title: Some functions
desc: Functions to inspect docstrings.
contents:
# the functions being documented in the package.
# you can refer to anything: class methods, modules, etc..
- get_object
- preview
```
Now that you have configured quartodoc, you can generate the reference
API docs with the following command:
``` bash
quartodoc build
```
This will create a `reference/` directory with an `index.qmd` and
documentation pages for listed functions, like `get_object` and
`preview`.
Finally, preview your website with quarto:
``` bash
quarto preview
```
## Rebuilding site
You can preview your `quartodoc` site using the following commands:
First, watch for changes to the library you are documenting so that your
docs will automatically re-generate:
``` bash
quartodoc build --watch
```
Second, preview your site:
``` bash
quarto preview
```
## Looking up objects
Generating API reference docs for Python objects involves two pieces of
configuration:
1. the package name.
2. a list of objects for content.
quartodoc can look up a wide variety of objects, including functions,
modules, classes, attributes, and methods:
``` yaml
quartodoc:
package: quartodoc
sections:
- title: Some section
desc: ""
contents:
- get_object # function: quartodoc.get_object
- ast.preview # submodule func: quartodoc.ast.preview
- MdRenderer # class: quartodoc.MdRenderer
- MdRenderer.render # method: quartodoc.MDRenderer.render
- renderers # module: quartodoc.renderers
```
The functions listed in `contents` are assumed to be imported from the
package.
## Learning more
Go [to the next
page](https://machow.github.io/quartodoc/get-started/basic-docs.html) to
learn how to configure quartodoc sites, or check out these handy pages:
- [Examples
page](https://machow.github.io/quartodoc/examples/index.html): sites
using quartodoc.
- [Tutorials
page](https://machow.github.io/quartodoc/tutorials/index.html):
screencasts of building a quartodoc site.
- [Docstring issues and
examples](https://machow.github.io/quartodoc/get-started/docstring-examples.html):
common issues when formatting docstrings.
- [Programming, the big
picture](https://machow.github.io/quartodoc/get-started/dev-big-picture.html):
the nitty gritty of how quartodoc works, and how to extend it.
Raw data
{
"_id": null,
"home_page": null,
"name": "quartodoc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "documentation, quarto",
"author": null,
"author_email": "Michael Chow <michael.chow@posit.co>",
"download_url": "https://files.pythonhosted.org/packages/73/83/912571f333eb2c063c69e080ff619ca4ee92864ffd87af6348fa08338b4a/quartodoc-0.7.6.tar.gz",
"platform": null,
"description": "# Overview\n\n[](https://github.com/machow/quartodoc/actions/workflows/ci.yml)\n\n**quartodoc** lets you quickly generate Python package API reference\ndocumentation using Markdown and [Quarto](https://quarto.org). quartodoc\nis designed as an alternative to\n[Sphinx](https://www.sphinx-doc.org/en/master/).\n\nCheck out the below screencast for a walkthrough of creating a\ndocumentation site, or read on for instructions.\n\n<p align=\"center\">\n<a href=\"https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed\">\n<img src=\"https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif\" width=\"75%\">\n</a>\n</p>\n\n<br>\n\n## Installation\n\n``` bash\npython -m pip install quartodoc\n```\n\nor from GitHub\n\n``` bash\npython -m pip install git+https://github.com/machow/quartodoc.git\n```\n\n<div>\n\n> **Install Quarto**\n>\n> If you haven\u2019t already, you\u2019ll need to [install\n> Quarto](https://quarto.org/docs/get-started/) before you can use\n> quartodoc.\n\n</div>\n\n## Basic use\n\nGetting started with quartodoc takes two steps: configuring quartodoc,\nthen generating documentation pages for your library.\n\nYou can configure quartodoc alongside the rest of your Quarto site in\nthe\n[`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html)\nfile you are already using for Quarto. To [configure\nquartodoc](https://machow.github.io/quartodoc/get-started/basic-docs.html#site-configuration),\nyou need to add a `quartodoc` section to the top level your\n`_quarto.yml` file. Below is a minimal example of a configuration that\ndocuments the `quartodoc` package:\n\n``` yaml\nproject:\n type: website\n\n# tell quarto to read the generated sidebar\nmetadata-files:\n - _sidebar.yml\n\n\nquartodoc:\n # the name used to import the package you want to create reference docs for\n package: quartodoc\n\n # write sidebar data to this file\n sidebar: _sidebar.yml\n\n sections:\n - title: Some functions\n desc: Functions to inspect docstrings.\n contents:\n # the functions being documented in the package.\n # you can refer to anything: class methods, modules, etc..\n - get_object\n - preview\n```\n\nNow that you have configured quartodoc, you can generate the reference\nAPI docs with the following command:\n\n``` bash\nquartodoc build\n```\n\nThis will create a `reference/` directory with an `index.qmd` and\ndocumentation pages for listed functions, like `get_object` and\n`preview`.\n\nFinally, preview your website with quarto:\n\n``` bash\nquarto preview\n```\n\n## Rebuilding site\n\nYou can preview your `quartodoc` site using the following commands:\n\nFirst, watch for changes to the library you are documenting so that your\ndocs will automatically re-generate:\n\n``` bash\nquartodoc build --watch\n```\n\nSecond, preview your site:\n\n``` bash\nquarto preview\n```\n\n## Looking up objects\n\nGenerating API reference docs for Python objects involves two pieces of\nconfiguration:\n\n1. the package name.\n2. a list of objects for content.\n\nquartodoc can look up a wide variety of objects, including functions,\nmodules, classes, attributes, and methods:\n\n``` yaml\nquartodoc:\n package: quartodoc\n sections:\n - title: Some section\n desc: \"\"\n contents:\n - get_object # function: quartodoc.get_object\n - ast.preview # submodule func: quartodoc.ast.preview\n - MdRenderer # class: quartodoc.MdRenderer\n - MdRenderer.render # method: quartodoc.MDRenderer.render\n - renderers # module: quartodoc.renderers\n```\n\nThe functions listed in `contents` are assumed to be imported from the\npackage.\n\n## Learning more\n\nGo [to the next\npage](https://machow.github.io/quartodoc/get-started/basic-docs.html) to\nlearn how to configure quartodoc sites, or check out these handy pages:\n\n- [Examples\n page](https://machow.github.io/quartodoc/examples/index.html): sites\n using quartodoc.\n- [Tutorials\n page](https://machow.github.io/quartodoc/tutorials/index.html):\n screencasts of building a quartodoc site.\n- [Docstring issues and\n examples](https://machow.github.io/quartodoc/get-started/docstring-examples.html):\n common issues when formatting docstrings.\n- [Programming, the big\n picture](https://machow.github.io/quartodoc/get-started/dev-big-picture.html):\n the nitty gritty of how quartodoc works, and how to extend it.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 quartodoc authors 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. ",
"summary": "Generate API documentation with Quarto.",
"version": "0.7.6",
"project_urls": {
"ci": "https://github.com/machow/quartodoc/actions",
"homepage": "https://machow.github.io/quartodoc",
"repository": "https://github.com/machow/quartodoc"
},
"split_keywords": [
"documentation",
" quarto"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b86c77f8fdb4de3d2077e81e5e30ba30ede712d14ad233f6deb4e25088364601",
"md5": "a5d13f283a4b2b0dca9a5f813135a97b",
"sha256": "d52f5c9e0b5842b74b93647c423af64c689d5aa0c43789ae4986a6044fde3733"
},
"downloads": -1,
"filename": "quartodoc-0.7.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a5d13f283a4b2b0dca9a5f813135a97b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 79814,
"upload_time": "2024-08-22T20:10:37",
"upload_time_iso_8601": "2024-08-22T20:10:37.020047Z",
"url": "https://files.pythonhosted.org/packages/b8/6c/77f8fdb4de3d2077e81e5e30ba30ede712d14ad233f6deb4e25088364601/quartodoc-0.7.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7383912571f333eb2c063c69e080ff619ca4ee92864ffd87af6348fa08338b4a",
"md5": "6f067bec54c7de6b35482b8432949867",
"sha256": "5513d66195f66d1edb547fdf9b4084532bd70b4ce44ce0f7a4e6a2cb55708626"
},
"downloads": -1,
"filename": "quartodoc-0.7.6.tar.gz",
"has_sig": false,
"md5_digest": "6f067bec54c7de6b35482b8432949867",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 768251,
"upload_time": "2024-08-22T20:10:38",
"upload_time_iso_8601": "2024-08-22T20:10:38.527034Z",
"url": "https://files.pythonhosted.org/packages/73/83/912571f333eb2c063c69e080ff619ca4ee92864ffd87af6348fa08338b4a/quartodoc-0.7.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-22 20:10:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "machow",
"github_project": "quartodoc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "quartodoc"
}
