Custom builder

Some packages use an API to send HTTP requests. This allows developers 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',
  },
});

Create content

The following example creates content at the specified path with the given JSON body.

http

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

{
    "@type": "Document",
    "title": "My New Document"
}

curl

curl -i -X POST http://localhost:8080/Plone/folder -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"@type": "Document", "title": "My New Document"}' --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.createContent({
  path: '/folder',
  data: {
    '@type': 'Document',
    title: 'My New Document',
  },
});