pdoc.html

It’s common for developers to build packages in Python that need auto-generated code documentation based off of Python strings.

To better support integrating that collection to your larger docs site, I’ve built out a {{<pdoc>}} shortcode that enables you to automatically target links for:

Supermodules
Submodules
Functions
Classes
Methods

How complex is the package?

If you are integrating pdoc documentation for a package that has submodules, use the default pdoc shortcode. For simple packages without submodules, use pdoc-2.

How it Works #

The {{<pdoc>}} shortcode accepts 3 positional args: type, target, and linktitle (optional). If linktitle is not set, it automatically configures the link text as show in the following sections.

pdoc #

Type (arg0)	Target (arg1)	Result
supermodule	`~pkg.super`	`/references/pkg/super`
submodule	`~pkg.super.sub`	`/references/pkg/super`
function	`~pkg.super.func`	`/references/pkg/super/sub#package.super.sub.func`
class	`~pkg.super.sub.class`	`/references/pkg/super/sub#package.super.sub.class`
method	`~pkg.super.sub.class.meth`	`/references/pkg/super/sub#pkg.super.sub.class.meth`

pdoc-2 #

Type (arg0)	Target (arg1)	Result
function	`~pkg.super.func_name`	`/references/pkg.html#pkg.func`
class	`~pkg.super.sub.class`	`/references/pkg.html#pkg.class`
method	`~pkg.super.sub.class.method`	`/references/pkg.html#pkg.class.meth`

Examples #

- {{< pdoc-2 "function" "~demo-package.demo_function" >}}
- {{< pdoc-2 "class" "~demo-package.DemoClass" >}}
- {{< pdoc-2 "method" "~demo-package.DemoClass.demo_method" >}}

Source Code #

Want to change the main directory?

You can change the default directory where this shortcode looks for pdoc collections by updating the value of $baseurl. Alternatively, you could make this shortcode more advanced and remove that static baseurl piece altogether.

<!-- layouts/shortcodes/det.html -->
{{ $type := index (.Params) 0 }}
{{ $path := index (.Params) 1 }} 
{{ $title := index (.Params) 2}}

{{ $baseurl := "/references/" }}
{{ $anchor := "" }}
{{ $linkText := "" }}

{{ $trimmed_path := strings.TrimPrefix "~" $path }}
{{ $path_parts := split $trimmed_path "." }}  

{{ if eq $type "supermodule" }}
  {{/*  url pattern for supermodule: {baseurl}/directory/supermodule/  */}}
  {{ $baseurl = printf "%s%s/%s/" $baseurl (index $path_parts 0) (index $path_parts 1) }}
  {{ $linkText = (index $path_parts 1) }}
{{ else if eq $type "submodule" }}
  {{/*  url pattern for submodule: {baseurl}/directory/supermodule/submodule.html */}}
  {{ $baseurl = printf "%s%s/%s/%s.html" $baseurl (index $path_parts 0) (index $path_parts 1) (index $path_parts 2) }}
  {{ $linkText = printf "%s.%s" (index $path_parts 2) (index $path_parts 1) }}
{{ else if eq $type "class" }}
  {{/*  url pattern for class: {baseurl}/directory/supermodule/submodule.html#directory.supermodule.submodule.class */}}
  {{ $baseurl = printf "%s%s/%s/%s.html" $baseurl (index $path_parts 0) (index $path_parts 1) (index $path_parts 2) }}
  {{ $anchor = printf "#%s.%s.%s.%s" (index $path_parts 0) (index $path_parts 1) (index $path_parts 2) (index $path_parts 3) }}
  {{ $linkText = printf "%s.%s()" (index $path_parts 2) (index $path_parts 3) }}
{{ else if eq $type "function" }}
  {{/*  url pattern for function: {baseurl}/directory/supermodule/submodule.html#directory.supermodule.submodule.function */}}
  {{ $baseurl = printf "%s%s/%s/%s.html" $baseurl (index $path_parts 0) (index $path_parts 1) (index $path_parts 2) }}
  {{ $anchor = printf "#%s.%s.%s.%s" (index $path_parts 0) (index $path_parts 1) (index $path_parts 2) (index $path_parts 3) }}
  {{ $linkText = printf "%s.%s()" (index $path_parts 2) (index $path_parts 3) }}
{{ else if eq $type "method" }}
  {{/*  url pattern for method: {baseurl}/directory/supermodule/submodule.html#directory.supermodule.submodule.class.method */}}
  {{ $baseurl = printf "%s%s/%s/%s.html" $baseurl (index $path_parts 0) (index $path_parts 1) (index $path_parts 2) }}
  {{ $anchor = printf "#%s.%s.%s.%s.%s" (index $path_parts 0) (index $path_parts 1) (index $path_parts 2) (index $path_parts 3) (index $path_parts 4) }}
  {{ $linkText = printf "%s.%s.%s()" (index $path_parts 2) (index $path_parts 3) (index $path_parts 4) }}
  {{else}}
    {{ errorf "The %q shortcode requires a type parameter as arg 0 (module, submodule, class, function, method). See %s" .Name .Position }}
{{ end }}


<a href="{{ $baseurl }}{{ $anchor }}" class="font-bold underline">{{with $title}}{{.}}{{else}}{{ $linkText }}{{end}}</a>

notice.html prod.html