Custom builder

Some packages use an API that sends HTTP requests. This allows the developer to focus on API calls instead of forming HTTP requests with low level utilities. For such packages, sphinxcontrib.httpexample supports custom builders.

The examples in this chapter use the @plone/client package, an agnostic library that provides easy access to the Plone REST API from a client written in TypeScript.

Register

Create a file at docs/plone_client.py.

In this file, define a custom method as your builder.

def build_plone_client_command(request: HTTPRequest): str
    result = ""
    # ...
    return result

Next, in docs/conf.py, register the builder with register_builder() to make it available.

from plone_client import build_plone_client_command
from sphinxcontrib.httpexample import register_builder

register_builder(
    # Name of the builder used in the directive
    "plone-client",
    # Function that builds the command
    build_plone_client_command,
    # Language for syntax highlighting
    "javascript",
    # Display name for the documentation tab
    "@plone/client"
)

The register_builder method has the following parameters.

name

The name of the builder to use in the reStructuredText or MyST directive.

builder

The function that builds the command to send an HTTP request.

language

The language, or lexer, to use for syntax highlighting.

label

The display name of the tab in the documentation.

Get content

The following example gets the content at the specified location.

http

GET /Plone/folder/my-document HTTP/1.1
Host: localhost:8080
Accept: application/json

curl

curl -i -X GET http://localhost:8080/Plone/folder/my-document -H "Accept: application/json"

@plone/client

import PloneClient from '@plone/client';

const cli = PloneClient.initialize({apiPath: 'http://localhost:8080/Plone'});

const { data, status } = cli.getContent({
  path: '/folder/my-document',
});

The following example gets the content at the specified location, using an expansion.

http

GET /Plone/folder/my-document?expand=breadcrumbs%2Cnavigation HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET 'http://localhost:8080/Plone/folder/my-document?expand=breadcrumbs%2Cnavigation' -H "Accept: application/json" --user admin:secret

@plone/client

import PloneClient from '@plone/client';

const cli = PloneClient.initialize({apiPath: 'http://localhost:8080/Plone'});

cli.login({username: 'admin', password: 'secret'});

const { data, status } = cli.getContent({
  path: '/folder/my-document',
  expanders: [
    'breadcrumbs',
    'navigation',
  ],
});

Update content

The following example updates the content at the specified location.

http

PATCH /Plone/folder/my-document HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
    "title": "My New Document Title"
}

curl

curl -i -X PATCH http://localhost:8080/Plone/folder/my-document -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"title": "My New Document Title"}' --user admin:admin

@plone/client

import PloneClient from '@plone/client';

const cli = PloneClient.initialize({apiPath: 'http://localhost:8080/Plone'});

cli.login({username: 'admin', password: 'admin'});

cli.updateContent({
  path: '/folder/my-document',
  data: {
    title: 'My New Document Title',
  },
});