pdoc.html

It’s common for developers to build packages in Python that need automatically 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