SSB Publish Markdown¶

Features¶

Write SSB articles using Quarto Markdown (qmd) files.
Create SSB components using Python:
- Highchart
- Factbox
Insert components in article using pandoc Markdown syntax.

Requirements¶

A VSCode or Jupyter service in Dapla Lab.
An SSB project.

Installation¶

poetry add ssb-pubmd

Latest development version:

poetry add ssb-pubmd@latest --source testpypi --allow-prereleases

Usage¶

poetry run ssb-pubmd create "My article title"

Follow further instructions in template file, and see the [Reference Guide] for details on creating components.

Contributing¶

Setup¶

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Alternative:

brew install uv

See link for installation on Windows.

Clone this repo.

git clone https://github.com/statisticsnorway/ssb-pubmd.git

Run tests¶

From the root folder (where pyproject.toml is), run:

uv run pytest

Testing the whole integration¶

When you push changes to a branch, the package is published to Test PyPI by the release-test.yaml workflow.
The test package can then be installed from a Dapla service and tested directly.

Steps¶

Use the following steps to test the most recently pushed change:

Open a Jupyter service in Dapla Dev.

Open a Jupyter terminal and run the following commands:

ssb-project create my-project
cd my-project
poetry source add testpypi https://test.pypi.org/simple/ -p explicit
poetry add "pandas<3"
poetry add ssb-pubmd@latest --source testpypi --allow-prereleases
poetry run ssb-pubmd create my-article

You can now continue testing in the same Dapla service. When pushing new changes, you need to update the test package in the Dapla service:
```
poetry update ssb-pubmd
```
Note that it takes about a minute (sometimes longer) for the PyPI Test package to become available.

Architecture¶

Dependency graph:

graph LR
   subgraph driving[Interface]
      cli[cli]
   end
   subgraph core[Core]
      project[create_project]
      article[render_article]
      docprocessor[Document processor]
      docpublisher[Document publisher]
   end
   subgraph driven[Adapters]
      cmsclient[Cms client]
      storage[Storage]
   end
   cmsservice[Cms service]

   cli --> project
   cli --> article --> docpublisher

   article --> docprocessor

   docpublisher --> cmsclient
   docpublisher --> storage

   cmsclient --> cmsservice

   classDef empty width:0px,height:0px;

Note: Cms Service refers to statisticsnorway/ssbno-app-pubmd.

General document flow:

The user asks to render their notebook file through the command-line interface.
The core method render_article uses the document processor to parse the file into a general Document object.
The Document object is passed into the document publisher, which extracts the content and passes it to the CMS client.
The CMS client sends the content to the CMS service and returns the parsed response.
The document publisher then stores the response, so that the id and path can be reused in future requests (to modify the existing CMS content instead of creating new content).

Flow of components:

Components are defined programmatically by the user in the notebook file.
When the notebook is executed by the document processor, the component data is stored in a temporary storage file (see the create function in __init__.py). After execution the component data is added to the Document object, and the temporary storage file is deleted (to ensure sensitive data is not stored on disk).
The document publisher then extracts all the components from the Document object and sends them to the Cms Client. During this process, the responses are used to modify the Document object. In particular, each component in the document tree is replaced with a html snippet from the response, which has a unique reference to the Cms content object.
Finally the whole document is extracted (as html) and passed to the Cms client, and then sent to the Cms service. Note that the Cms service will be able to parse the component references because of the process in the previous step.

Updates to mimir content types¶

This package exposes a Python interface to mimir content types in models.py. When mimir types change, the corresponding Python interface can be updated following these steps.

Adding a new field¶

There are two simple steps of adding an extra field to an exposed content type:

Decide how the extra field should be exposed to the user.
- The exposed models are defined in models.py.
- Example of adding a required string field:
```
from pydantic import BaseModel
class MyModel(BaseModel):
     extra_field: str
```
- If the string field should be optional, a default value is given:
```
from pydantic import BaseModel
class MyModel(BaseModel):
     extra_field: str | None = None
     another_field: str = "default-string"
```
- See existing models for more examples. Remember to add a description of the field in the documentation string.
Add the extra field to the payload (that will be sent to the CMS).
- The payload is created in the source file adapters/cms_client/mimir.py.
- If we have added a field to the Highchart model, we would add it to the payload in the method _create_highchart_payload.
- The payload must match the Mimir content type. For instance, Highchart has an xlabel field which should be given as xAxisLabel in the payload.
```
payload["xAxisTitle"] = data.xlabel
```
- The easiest way to see how the payload should look is to use the Content Viewer in Content Studio, or the generated Enonic types.

License¶

Distributed under the terms of the MIT license, SSB Publish Markdown is free and open source software.

Issues¶

If you encounter any problems, please file an issue along with a detailed description.

Credits¶

This project was generated from Statistics Norway’s SSB PyPI Template.