Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/user_guide/05-configuration.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -322,6 +322,19 @@ the build.
Your own site publishes `objects.inv` at its root, so other projects can point a source at
your documentation in the same way.

### Aliases for Your Own Package

`interlinks.aliases` lists the module names your prose uses for your own package. With
`aliases: [sc]` for Sciris, `` `sc.findinds()` `` and `` [](`sc.findinds`) `` both resolve as
`sciris.findinds`:

```yaml
interlinks:
aliases: [sc]
```

If a source lists the same alias, yours wins.

### Parentheses on Function Links

A function or method link displays a trailing `()`, so `[](`decode`)` renders as `decode()`. Class
Expand Down
39 changes: 39 additions & 0 deletions docs/user_guide/06-api-documentation.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -728,6 +728,45 @@ Quarto rendering) but differ in where configuration lives and how much you need
5. **Build and preview.** Run `great-docs build` followed by `great-docs preview`. Your reference
pages should render with the same content, now with Great Docs' enhanced styling and features.

### Keeping quartodoc for the API Reference

If you'd rather keep your quartodoc reference pages exactly as they are, Great Docs can run
quartodoc for you instead of generating the reference itself. Install a quartodoc distribution,
such as the maintained [quartopydoc](https://github.com/sciris/quartopydoc) fork:

```bash
pip install great-docs[quartodoc]
```

Then copy the `quartodoc:` block from your `_quarto.yml` into `great-docs.yml` unchanged:

```{.yaml filename="docs/great-docs.yml"}
quartodoc:
package: my_package
style: pkgdown
dir: api
sections:
- title: Core
desc: Primary interface
contents:
- MyClass
- helper_function
```

On each build, quartodoc writes the reference pages in place of Great Docs, and its sidebar
(grouped by your sections) becomes the reference sidebar, with no `metadata-files` entry needed.
Everything else about the API stays Great Docs': it still discovers your API (honoring `reference`
and the other settings on this page) for `llms.txt`, `llms-full.txt`, and the agent skill, and
cross-references across the site resolve to quartodoc's pages too. `llms.txt` links to quartodoc's
pages, listing only the objects quartodoc documents.
`package` defaults to your detected package and `dir` to `reference`; the navbar's Reference link
follows `dir`. Any other quartodoc option works as it does in quartodoc, including `sidebar`
options such as `collapse-level`.

To also carry over your site's appearance, see [Raw Quarto Settings](theming.qmd#quarto-passthrough).
If your docs write names with a module alias, such as `sc.findinds()` for `import sciris as sc`,
set `interlinks.aliases` (see [Cross-Referencing](cross-referencing.qmd)) so they link too.

## Next Steps

Great Docs handles the tedious parts of API documentation (discovery, classification, layout,
Expand Down
16 changes: 12 additions & 4 deletions docs/user_guide/11-theming.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -565,13 +565,21 @@ format:
```

::: {.callout-warning}
Replacing a list replaces Great Docs' own entries too. For example, setting `format.html.theme`
drops `great-docs.scss`, the stylesheet behind most of Great Docs' styling, and setting
Replacing a list replaces Great Docs' own entries too. For example, setting
`format.html.include-in-header` drops the scripts Great Docs injects. For everyday settings, prefer
`site` (which merges into `format.html` before Great Docs adds its own entries), `include_in_header`,
and the other dedicated options on this page.
`site`, `include_in_header`, and the other dedicated options on this page. The one exception is
`format.html.theme`: Great Docs puts its own stylesheet, `great-docs.scss`, back in right after the
base theme, since its widgets need it, so your SCSS files still take precedence.
:::

To keep the look of an existing site's pages entirely, also set `styles: widgets`. Great Docs then
styles only its own widgets and the page layout, leaving page content (heading and code fonts,
link and table styles) to your Quarto theme and SCSS:

```{.yaml filename="docs/great-docs.yml"}
styles: widgets
```

## Logo

Great Docs can display a logo in the navbar instead of the plain-text package name. Logos are
Expand Down
8 changes: 8 additions & 0 deletions docs/user_guide/12-cross-referencing.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,14 @@ See [](`numpy.ndarray`) for the array type, or [](`np.ndarray`) using the alias.
Code autolinks stay inside your own project. A bare `` `array` `` in your prose is left alone
rather than linked into another project's documentation.

Your own package can have an alias too. If your users write `import sciris as sc`, list `sc` under
`interlinks.aliases`, and `` `sc.findinds()` `` in your prose links to `sciris.findinds()`:

```yaml
interlinks:
aliases: [sc]
```

See [Configuration](05-configuration.qmd) for the full set of fields a source accepts.

## When a Short Name Is Ambiguous
Expand Down
6 changes: 6 additions & 0 deletions great_docs/_interlinks/index.py
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,7 @@ def build_index(
claims: AliasClaims,
external: Sequence[tuple[Source, Inventory]],
*,
aliases: Sequence[str] = (),
add_function_parentheses: bool = True,
) -> Index:
"""
Expand All @@ -240,6 +241,9 @@ def build_index(
The short names this project's documented objects claim.
external :
Each source and the inventory read for it.
aliases :
Module aliases prose uses for this project's own package. They win
over a source's alias of the same spelling.
add_function_parentheses :
Whether a link to a function or method shows a trailing `()`.

Expand Down Expand Up @@ -282,6 +286,8 @@ def add(name: str, rank: int, priority: int, entry: IndexEntry) -> None:
roots = root_modules(inv)
for alias in source.aliases:
prefixes[alias] = roots
for alias in aliases:
prefixes[alias] = root_modules(local)

ordered = {
name: tuple(entry for _, entry in sorted(items, key=lambda pair: pair[0]))
Expand Down
1 change: 1 addition & 0 deletions great_docs/_interlinks/project.py
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ def build_project_index(
local,
claims,
sources.read,
aliases=config.interlinks_aliases,
add_function_parentheses=config.interlinks_add_function_parentheses,
)
write_index(index, project_path / "_inv" / "index.lua")
Expand Down
1 change: 1 addition & 0 deletions great_docs/_lint.py
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,7 @@ def run_lint(
create_inventory(importable_name, "", documented),
AliasClaims.make(documented),
sources.read,
aliases=docs._config.interlinks_aliases,
)
_check_cross_references(
pkg, importable_name, exports, documented, index, sources.unread, result
Expand Down
33 changes: 33 additions & 0 deletions great_docs/_utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,39 @@ def merge_quarto_overrides(config: dict, overrides: dict) -> dict:
return result


GREAT_DOCS_SCSS = "great-docs.scss"


def with_great_docs_scss(theme: str | list | dict, position: int | None = None) -> str | list | dict:
"""
Add great-docs' stylesheet to a Quarto `theme` value

Handles each form `theme` takes: a theme name, a list of themes and SCSS
files, or a mapping of such values by mode (`light`, `dark`). A value that
already includes the stylesheet is returned unchanged.

Parameters
----------
theme
The `format.html.theme` value.
position
Where to insert the stylesheet in each list; `None` appends it, so it
overrides the rest, while `1` puts it right after the base theme, so
the user's own SCSS files override it.

Returns
-------
str | list | dict
The theme value with the stylesheet added.
"""
if isinstance(theme, dict):
return {mode: with_great_docs_scss(value, position) for mode, value in theme.items()}
themes = [theme] if isinstance(theme, str) else list(theme)
if GREAT_DOCS_SCSS not in themes:
themes.insert(len(themes) if position is None else position, GREAT_DOCS_SCSS)
return themes


GITIGNORE_CONTENT = """# Great Docs build directory
# This directory is ephemeral and regenerated on each build
# Do not commit this directory to version control
Expand Down
33 changes: 33 additions & 0 deletions great_docs/assets/great-docs.default.yml
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,9 @@ parser: numpy
# aliases: [np]
interlinks:
sources: {} # Projects to link to; none by default
# Module aliases your prose uses for this project's own package, so that
# `sc.findinds()` links like `sciris.findinds()` (for `import sciris as sc`).
aliases: []
# A link to a function or method shows a trailing "()", as `decode()` rather
# than `decode`. Links to classes never show one.
add_function_parentheses: true
Expand Down Expand Up @@ -274,6 +277,17 @@ site:
# mainfont: "Source Sans Pro"
quarto: {}

# Styles
# ------
# What Great Docs styles. Its widgets (navbar buttons, copy buttons, badges and
# the like) and page layout are always styled; page content (heading and code
# fonts, link and table styles) is optional.
# : all - (default) the whole page
# : widgets - only the widgets and layout, leaving page content to the Quarto
# theme and any SCSS you add to it (for example, to keep the look of an
# existing Quarto site)
styles: all

# Page Metadata
# -------------
# Show page timestamps in footer
Expand Down Expand Up @@ -409,6 +423,25 @@ csl: null
# - another_func
reference: []

# quartodoc API Reference
# -----------------------
# Generate the API reference with quartodoc (e.g. the quartopydoc fork,
# `pip install great-docs[quartodoc]`) instead of great-docs' own renderer.
# Takes the same settings as the `quartodoc:` block of a Quarto project's
# `_quarto.yml`, so an existing block can be copied over unchanged. `package`
# defaults to the detected package and `dir` to "reference". When set, the
# `reference` option above is ignored.
#
# quartodoc:
# style: pkgdown
# parser: google
# sections:
# - title: Utilities
# desc: Helper functions
# contents:
# - mymodule
quartodoc: {}

# Inline Methods
# --------------
# Whether class methods get their own pages or stay inline.
Expand Down
Loading
Loading