Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

documenting-julia-package

/documenting-julia-package

Pomaga dodać, zbudować i opublikować dokumentację pakietu Julia z Documenter.jl: układ docs/, makedocs i deploydocs, bloki @docs, doctesty i wdrożenie na GitHub Pages.

Licencja
MIT
Ostatnia zmiana repozytorium
26.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
4
Przestarzałość

Brak sygnałów. Repozytorium zmienione 26.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pomaga dodać, zbudować i opublikować dokumentację pakietu Julia z Documenter.jl: układ docs/, makedocs i deploydocs, bloki @docs, doctesty i wdrożenie na GitHub Pages.

Oryginalny opis (EN)

Use when you add, build, or publish documentation for a Julia package with Documenter.jl: the `docs/` layout, `docs/Project.toml`, `makedocs`/`deploydocs`, `@docs` and docstring blocks, doctests, and GitHub Pages deployment

Jak działa

  1. Step 1: Create the docs/ layout
  2. Step 2: Set up the doc build environment
  3. Step 3: Write docs/make.jl
  4. Step 4: Add docstrings and pages
  5. Step 5: Build locally
  6. Step 6: Doctests keep examples honest
  7. Step 7: Deploy to GitHub Pages
  8. Security notes
  9. Pitfalls
Sekcje z nagłówków SKILL.md, w oryginale · 249 linii, 1 115 słów
Podgląd SKILL.md
---
name: documenting-julia-package
description: Use when you add, build, or publish documentation for a Julia package with Documenter.jl: the `docs/` layout, `docs/Project.toml`, `makedocs`/`deploydocs`, `@docs` and docstring blocks, doctests, and GitHub Pages deployment
---

# Documenting a Julia package with Documenter.jl

[Documenter.jl](https://documenter.juliadocs.org/stable/) builds a single,
cross-linked HTML site from Markdown files plus the package's docstrings, and
publishes it to GitHub Pages. This skill sets up the standard `docs/` layout,
wires doctests so examples cannot go stale, and deploys on CI.

Assume the package is named `MyPkg` and lives at the repository root (see
[[generating-julia-package]] for the package layout). Write docstrings as
described in [[developing-julia-package]].

## Step 1: Create the `docs/` layout

```
MyPkg/
├── docs/
│   ├── Project.toml   # doc-build environment
│   ├── make.jl        # build script
│   └── src/
│       └── index.md   # landing page (the name is mandatory for HTML output)
├── src/
│   └── MyPkg.jl
└── Project.toml
```

`DocumenterTools.generate` can create this skeleton, but hand-writing it is
simple enough for the default layout.

## Step 2: Set up the doc build environment

**Julia 1.13 development baseline:** add `docs` to the package's `[workspace]`
so the documentation environment resolves together with the package. Include
other development projects such as `test` and `benchmark` in the same list when
they exist:

```toml
[workspace]
projects = ["docs"] # Include "test" or "benchmark" too when those projects exist.
```

Declare Documenter and the local package in `docs/Project.toml`. Workspace
projects do not inherit the root package's dependencies:

```toml
[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
MyPkg = "<UUID from the root Project.toml>"

[sources]
MyPkg = {path = ".."}

[compat]
Documenter = "1"
```

Resolve the doc environment from the repository root:

```sh
julia --project=docs -e 'using Pkg; Pkg.instantiate(; workspace=true)'
```

Do **not** add Documenter to the package's own `[deps]` — it is a doc-build
dependency, not a runtime one.

## Step 3: Write `docs/make.jl`

```julia
using Documenter, MyPkg

makedocs(;
    sitename = "MyPkg.jl",
    modules = [MyPkg],
    authors = "Your Name",
    pages = [
        "Home" => "index.md",
        "API reference" => "api.md",
    ],
)

deploydocs(; repo = "github.com/USER_NAME/MyPkg.jl.git")
```

- `modules = [MyPkg]` tells Documenter which modules own the docstrings; that
  also prevents a `Base` method you extend from dragging in unrelated docs.
- If the package was added by local path (a dev dependency), also pass
  `remotes = nothing`, otherwise Documenter tries to build source links against
  a remote that does not exist.
- `deploydocs` needs no protocol prefix in `repo` (no `https://`, no `git@`).
- Keep `deploydocs` out of local builds only if you must; it is a no-op outside
  CI unless it decides to deploy.

## Step 4: Add docstrings and pages

`docs/src/index.md` is the landing page. Splice docstrings into Markdown with
`@docs` (one object per line), and use `@meta` to set the module for a page:

````markdown
# MyPkg.jl

```@meta
CurrentModule = MyPkg
```

## Reference

```@docs
fit_model
FitResult
```
````

- `@autodocs` includes every docstring in a module; `@contents` builds a
  table of contents; `@index` builds a flat docstring index.
- Cross-reference within the docs with `[`fit_model`](@ref)` and section
  headings with `[Home](@ref)`.
- Control the sidebar order and grouping with the `pages` argument (shown in
  Step 3) and hide pages with `Documenter.hide`.

## Step 5: Build locally

```sh
$ julia --project=docs docs/make.jl
```

Output lands in `docs/build/`. Documenter uses pretty URLs
(`src/foo.md` → `foo/index.html`), which browsers do not resolve for local
`file://` paths, so preview over HTTP instead:

```sh
$ julia -e 'using LiveServer; serve(dir="docs/build")'
# or
$ python3 -m http.server --bind localhost --directory docs/build
```

Add `docs/build/` to `.gitignore`; never commit build output to the main branch.

## Step 6: Doctests keep examples honest

A `jldoctest` block is executed and its output compared during `makedocs`
(failures are fatal by default). Use this for any example a reader can run:

````markdown
```jldoctest
julia> 1 + 1
2
```
````

- Definitions do not carry between blocks; give blocks the same label
  (`jldoctest mylabel`) to share scope, or use `setup = :(...)` for short
  definitions.
- Filter non-deterministic output (timings, addresses, versions) with
  `filter = r"..." => s"..."` or a page-level `DocTestFilters` in an `@meta`
  block.
- Doctests inside docstrings run only if their module is listed in `modules`.
- Update outdated doctests deliberately with `doctest(MyPkg; fix = true)` (or
  `makedocs(; doctest = :fix)`), then review the diff before committing.

To run doctests as part of the normal test suite, add Documenter to the test
project (see [[testing-julia-package]]) and call `doctest` in
`test/runtests.jl`; it behaves like a `@testset`:

```julia
using Test, Documenter, MyPkg

@testset "MyPkg" begin
    doctest(MyPkg; manual = false)  # manual = false checks docstrings only
end
```

Run it with the other tests (see [[testing-julia-package]]).

## Step 7: Deploy to GitHub Pages

Create `.github/workflows/documentation.yml`:

```yaml
name: Documentation

on:
  push:
    branches: [main]   # your development branch
    tags: '*'
  pull_request:
  workflow_dispatch:

jobs:
  build:
    permissions:
      contents: write   # required to push to gh-pages with GITHUB_TOKEN
      pull-requests: read
      statuses: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: julia-actions/setup-julia@v3
        with:
          version: '1'
      - uses: julia-actions/cache@v3
      - name: Install dependencies
        shell: julia --color=yes --project=docs {0}
        run: |
          using Pkg
          Pkg.instantiate(; workspace=true)
      - name: Build and deploy
        run: julia --color=yes --project=docs docs/make.jl
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

- In the repository's **Settings → Pages**, set the source to the `gh-pages`
  branch (root). Documenter creates the branch on first deploy.
- **Same-repo deploy:** `GITHUB_TOKEN` works and needs `contents: write`. For
  tagged versions, TagBot must also be able to trigger the workflow — configure
  it with an SSH deploy key (see below).
- **Cross-repo or tag-triggered deploy:** generate an SSH deploy key with
  `DocumenterTools.genkeys(user="USER", repo="MyPkg.jl")`, add the public key as
  a write-enabled **Deploy key** on the target repository, and store the
  base64-encoded private key as the `DOCUMENTER_KEY` **repository secret** on
  the repository running the workflow.
- Add the docs badge to `README.md` once deployed:
  `[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://USER.github.io/MyPkg.jl/stable)`.

## Security notes

- `DOCUMENTER_KEY` is an **unencrypted private key** granting write access to
  the target repository. Never print it in logs, paste it into issues, or
  commit it; store it only as an encrypted repository secret. Use the `Secrets`
  tab (not `Variables`) and *repository* secrets (not environment secrets).
- `makedocs` and `doctest` execute the package's code and any code in
  `jldoctest` blocks. Only build documentation for code you trust, and remember
  the doc CI runs that code on every push.

## Pitfalls

- **Missing `index.md`.** HTML output requires `docs/src/index.md`; other pages
  are optional.
- **Docstrings not found.** The owning module must be in `makedocs`'s `modules`,
  and `@docs` resolves names in `Main` unless a `CurrentModule` is set.
- **`remotes = nothing` forgotten** for a locally dev'd package, causing broken
  source links.
- **Committing `docs/build/`.** Gitignore it; generated files belong on
  `gh-pages`, which Documenter manages.
- **Editing doctest output by hand.** Let `doctest(MyPkg; fix = true)` regenerate
  it, then inspect the diff; the fixer can rarely rewrite the wrong snippet.
- **Unpinned Documenter.** A `[compat]` bound stops a new major release from
  breaking your build unexpectedly.

Wersje

W bazie nie ma innych skilli o nazwie documenting-julia-package.

Migawka bazy z 13.11.2026 · wersja paczki a2bad71f9cb7 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 98julia-package-dev
    Pomaga wydać i utrzymać pakiet Julia: podbicie wersji, rejestrację w General, zakresy compat, dokumentację i CI.
  • 100generating-julia-package
    Prowadzi przez tworzenie nowego pakietu lub środowiska projektu w Julii: układ katalogów, Project.toml, src, UUID, zależności i przygotowanie do rejestracji.
  • 100developing-julia-package
    Wspiera pracę nad kodem istniejącego pakietu Julia: układ modułów i include, multiple dispatch, adnotacje i stabilność typów, formatowanie oraz docstringi.
  • 85julia-evaluation
    Uruchamia i testuje kod Julia w trwałej sesji REPL oraz przeładowuje zmiany bez restartu.
  • 100julia-pro
    Pisze i optymalizuje programy w Julii 1.10+, z wielokrotnym dyspozytorowaniem, zarządzaniem pakietami i kodem do obliczeń numerycznych.
  • 100codebase-documenter
    Pisze dokumentację bazy kodu: README, dokumenty architektury, przewodniki startowe, dokumentację API i komentarze w kodzie, aby ułatwić start nowym programistom.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.