diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4976069f..0ce1d113 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -110,58 +110,3 @@ jobs: - name: Build docs run: | make docs-build - # push to netlify ------------------------------------------------------- - # set release name ---- - - - name: Configure pull release name - if: ${{github.event_name == 'pull_request'}} - run: | - echo "RELEASE_NAME=pr-${PR_NUMBER}" >> $GITHUB_ENV - env: - PR_NUMBER: ${{ github.event.number }} - - name: Configure branch release name - if: ${{github.event_name != 'pull_request'}} - run: | - # use branch name, but replace slashes. E.g. feat/a -> feat-a - echo "RELEASE_NAME=${GITHUB_REF_NAME/\//-}" >> $GITHUB_ENV - # deploy ---- - - name: Create Github Deployment - uses: bobheadxi/deployments@v0.4.3 - id: deployment - with: - step: start - token: ${{ secrets.GITHUB_TOKEN }} - env: ${{ env.RELEASE_NAME }} - ref: ${{ github.head_ref }} - transient: true - logs: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}" - - - name: Netlify docs preview - run: | - npm install -g netlify-cli - # push main branch to production, others to preview -- - if [ "${ALIAS}" == "main" ]; then - netlify deploy --dir=docs/_build --alias="main" - else - netlify deploy --dir=docs/_build --alias="${ALIAS}" - fi - env: - NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} - NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} - ALIAS: ${{ steps.deployment.outputs.env }} - - - name: Update Github Deployment - uses: bobheadxi/deployments@v0.4.3 - if: ${{ always() }} - with: - step: finish - token: ${{ secrets.GITHUB_TOKEN }} - status: ${{ job.status }} - deployment_id: ${{ steps.deployment.outputs.deployment_id }} - env_url: "https://${{ steps.deployment.outputs.env }}--quartodoc.netlify.app" - logs: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}" - - uses: peaceiris/actions-gh-pages@v3 - if: github.event_name == 'release' - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: docs/_build diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..b211e7f5 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,45 @@ +name: Docs + +on: + workflow_dispatch: + push: + branches: ["main"] + +# needed for peaceiris/actions-gh-pages to push the gh-pages branch +permissions: + contents: write + +# never let two deploys race each other onto gh-pages +concurrency: + group: docs-deploy + cancel-in-progress: true + +jobs: + deploy-docs: + name: "Build and deploy docs" + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install uv + uses: astral-sh/setup-uv@v4 + with: + enable-cache: true + - name: Set up Python 3.10 + run: uv python install 3.10 + - name: Install dependencies + run: | + uv sync --group dev + # TODO: temporary installs for examples + # once quartodoc is stable we should move into their own libraries + uv pip install shiny shinylive + uv pip install --no-deps dascore==0.0.8 + - uses: quarto-dev/quarto-actions/setup@v2 + - name: Build docs + run: | + make docs-build + - name: Deploy to gh-pages + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/_build + publish_branch: gh-pages diff --git a/.gitignore b/.gitignore index 0a8c2b4f..6422918e 100644 --- a/.gitignore +++ b/.gitignore @@ -106,13 +106,6 @@ ipython_config.py # are the source of truth, and uv regenerates this on every sync uv.lock -# `make docs-build-readme` renders into the repo root, leaving these behind -# alongside the README it generates -/index.html -/objects.json -/objects.txt -/objects-test.txt - # PEP 582; used by e.g. github.com/David-OConnor/pyflow __pypackages__/ diff --git a/Makefile b/Makefile index fc80a096..ac2ed585 100644 --- a/Makefile +++ b/Makefile @@ -1,9 +1,5 @@ EXAMPLE_INTERLINKS=quartodoc/tests/example_interlinks -README.md: README.qmd - quarto render $< - - # These 2 rules are used to generate the example_interlinks folder, # which contains a full example for the interlinks filter to be tested @@ -18,17 +14,6 @@ $(EXAMPLE_INTERLINKS)/test.md: $(EXAMPLE_INTERLINKS)/test.qmd _extensions/interl -docs-build-readme: export BUILDING_README = 1 -docs-build-readme: - # note that the input file is named GITHUB.qmd, because quart does not - # render files named README.qmd, and it is very cumbersome to work around - # this very strange behavior - cd docs \ - && quarto render GITHUB.qmd \ - --to gfm \ - --output README.md \ - --output-dir .. - docs-build: export PLUM_SIMPLE_DOC=1 docs-build: cd docs && uv run quartodoc build --verbose diff --git a/README.md b/README.md index 4603d5b3..26aedbbc 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,12 @@ -# Overview - **quartopydoc** lets you quickly generate Python package API reference documentation using Markdown and [Quarto](https://quarto.org). It is designed as an alternative to [Sphinx](https://www.sphinx-doc.org/en/master/). -`quartopydoc` is a fork of [`quartodoc`](https://github.com/machow/quartodoc), created by Michael Chow at Posit but no longer maintained. Only the name of the distribution differs: you still import `quartodoc`, still run `quartodoc build`, and still configure a `quartodoc:` section in your `_quarto.yml`. For what this fork adds on top, see [differences from quartodoc](#differences-from-quartodoc). For Posit's more modern document generation package that is a successor to `quartodoc`, see [Great Docs](https://posit-dev.github.io/great-docs/). +`quartopydoc` is a fork of [`quartodoc`](https://github.com/machow/quartodoc), created by Michael Chow at Posit but no longer maintained. Only the name of the distribution differs: you still import `quartodoc`, still run `quartodoc build`, and still configure a `quartodoc:` section in your `_quarto.yml`. For what this fork adds on top, see [differences from quartodoc](#differences-from-quartodoc). For Posit’s more modern document generation package that is a successor to `quartodoc`, see [Great Docs](https://posit-dev.github.io/great-docs/). Check out the below screencast for a walkthrough of creating a documentation site, or read on for instructions.

- - - +


@@ -29,11 +25,7 @@ python -m pip install git+https://github.com/sciris/quartopydoc.git Note that the package is installed as `quartopydoc`, but imported as `quartodoc`. -> [!IMPORTANT] -> -> ### Install Quarto -> -> If you haven’t already, you’ll need to [install Quarto](https://quarto.org/docs/get-started/) before you can use quartodoc. +> **Important:** if you haven’t already, you’ll need to [install Quarto](https://quarto.org/docs/get-started/) before you can use quartodoc. ## Basic use diff --git a/docs/GITHUB.qmd b/docs/GITHUB.qmd deleted file mode 100644 index 8666a044..00000000 --- a/docs/GITHUB.qmd +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: quartopydoc -replace_base_domain: "https://sciris.github.io/quartopydoc" -replace_rel_path: "/get-started" -filters: - - _filters/replace-readme-links.lua -format: gfm - -# autolinked references resolve to ./api/*.html, which is not a valid path -# from the README at the repo root -interlinks: - autolink: false ---- - -```{=markdown} -[![CI](https://github.com/sciris/quartopydoc/actions/workflows/ci.yml/badge.svg)](https://github.com/sciris/quartopydoc/actions/workflows/ci.yml) -``` - -{{< include get-started/overview.qmd >}} diff --git a/docs/_filters/replace-readme-links.lua b/docs/_filters/replace-readme-links.lua deleted file mode 100644 index c7c9dac8..00000000 --- a/docs/_filters/replace-readme-links.lua +++ /dev/null @@ -1,37 +0,0 @@ -function Meta(meta) - replace_base_domain = tostring(meta.replace_base_domain[1].text) - replace_rel_path = tostring(meta.replace_rel_path[1].text) -end - --- pandoc Link object: replace the .qmd in the target with .html -function Link(link) - -- replace .qmd with .html in target - -- replace beginning with replace_base_domain, accounting for / and ./ in paths - -- e.g. ./overview.qmd -> {replace_rel_path}/get-started/overview.html - -- e.g. /index.qmd -> {replace_base_domain}/index.html - -- e.g. https://example.com -> https://example.com - if link.target:match("%.qmd$") or link.target:match("%.qmd#.*$") then - link.target = link.target:gsub("%.qmd", ".html") - if link.target:match("^%./") then - link.target = link.target:gsub("^%./", replace_base_domain .. replace_rel_path .. "/") - end - if link.target:match("^/") then - link.target = link.target:gsub("^/", replace_base_domain .. "/") - end - -- if target does not start with http, do same as above - if not link.target:match("^http") then - link.target = replace_base_domain .. replace_rel_path .. "/" .. link.target - end - end - - return link -end - -return { - { - Meta = Meta - }, - { - Link = Link - } -} diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 9ad2279a..a4a1627f 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -31,6 +31,8 @@ interlinks: website: title: "quartopydoc" + site-url: https://sciris.github.io/quartopydoc/ + repo-url: https://github.com/sciris/quartopydoc/ page-navigation: true navbar: left: diff --git a/docs/get-started/overview.qmd b/docs/get-started/overview.qmd index e85fdf05..d2c91c64 100644 --- a/docs/get-started/overview.qmd +++ b/docs/get-started/overview.qmd @@ -2,200 +2,8 @@ title: Overview aliases: - ../index.html -jupyter: - kernelspec: - display_name: Python 3 (ipykernel) - language: python - name: python3 --- + -**quartopydoc** lets you quickly generate Python package API reference documentation using Markdown and [Quarto](https://quarto.org). -It is designed as an alternative to [Sphinx](https://www.sphinx-doc.org/en/master/). - -quartopydoc is a fork of [quartodoc](https://github.com/machow/quartodoc), created by Michael Chow at Posit. Only the name of the distribution differs: you still import `quartodoc`, still run `quartodoc build`, and still configure a `quartodoc:` section in your `_quarto.yml`. For what the fork adds on top, see [differences from quartodoc](#differences-from-quartodoc). - - -Check out the below screencast for a walkthrough of creating a documentation site, or read on for instructions. - - -```{python} -#| echo: false -#| output: asis - -# this code ensures that the proper html for the tutorial screencast is used, -# depending on whether it's being rendered for the github README, or doc site. -import os - -if "BUILDING_README" in os.environ: - # I don't know why, but we need to repeat the Installation header here. - # or quarto makes it disappear when we generate the readme - print(""" -

- - - -

- -
- -""") -else: - print(""" -
-
-""") - -``` - -## Installation - -```bash -python -m pip install quartopydoc -``` -or from GitHub - -```bash -python -m pip install git+https://github.com/sciris/quartopydoc.git -``` - -Note that the package is installed as `quartopydoc`, but imported as `quartodoc`. - -:::{.callout-important} - -### Install Quarto - -If you haven't already, you'll need to [install Quarto](https://quarto.org/docs/get-started/) before you can use quartodoc. -::: - - -## 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](./basic-docs.qmd#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: - - reference/_sidebar.yml - -# tell quarto to read the generated styles -format: - html: - css: - - reference/_styles-quartodoc.css - -quartodoc: - # the name used to import the package you want to create reference docs for - package: quartodoc - - # write sidebar and style data - sidebar: reference/_sidebar.yml - css: reference/_styles-quartodoc.css - - 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. - -Instead of listing them out, you can set `contents: auto` to document every public submodule of the package: - -```yaml -quartodoc: - package: quartodoc - sections: - - title: All modules - desc: "" - contents: auto -``` - - -## Differences from quartodoc - -Everything documented for quartodoc still applies. On top of it, quartopydoc adds: - -**The `qpyd` and `qpynb` commands.** Where `quartodoc build` generates your API reference pages, `qpyd` wraps the whole docs lifecycle — pre-render builds, rendering, previewing, publishing, and scaffolding a new docs folder — and `qpynb` runs, checks, converts, and cleans notebooks in parallel. See [the qpyd CLI](qpyd-cli.qmd). - -**`contents: auto`.** Document every public submodule of a package without listing them out, as shown [above](#looking-up-objects). Private modules and test modules are skipped. - -**griffe 2.x.** quartopydoc requires griffe 2.0 or later, and tracks its current API. - -Note that quartopydoc is not a drop-in replacement in one respect: installing both it and quartodoc into the same environment will conflict, since both provide the `quartodoc` package and the `quartodoc` command. - - -## Learning more - -Go [to the next page](basic-docs.qmd) to learn how to configure quartodoc sites, or check out these handy pages: - -* [The qpyd CLI](./qpyd-cli.qmd): building, previewing, and publishing a site, and managing notebooks. -* [Examples page](/examples/index.qmd): sites using quartodoc. -* [Tutorials page](/tutorials/index.qmd): screencasts of building a quartodoc site. -* [Docstring issues and examples](./docstring-examples.qmd): common issues when formatting docstrings. -* [Programming, the big picture](./dev-big-picture.qmd): the nitty gritty of how quartodoc works, and how to extend it. +{{< include ../../README.md >}}