137 lines
4.3 KiB
Markdown
137 lines
4.3 KiB
Markdown
# xconfluencebuilder
|
|
|
|
This program is a drop-in replacement for the [Atlassian Confluence Builder for
|
|
Sphinx](https://github.com/sphinx-contrib/confluencebuilder). It
|
|
exports/dumps/archives the build output of the confluencebuilder Sphinx builder
|
|
into a generic interchangeable format, which can be used in conjunction with
|
|
other publishers than the built-in one. The program does not require
|
|
connectivity to a Confluence instance.
|
|
|
|
The program may be useful in circumstances where a Python3 runtime is not
|
|
available on the machine responsible for publishing to Confluence.
|
|
|
|
For more information on why this program exists, please refer to
|
|
[confluencebuilder Issue
|
|
823](https://github.com/sphinx-contrib/confluencebuilder/issues/823).
|
|
|
|
For a reference implementation of an external publisher, please refer to
|
|
[PSConfluencePublisher](https://bitbucket.org/victorykit/psconfluencepublisher),
|
|
a standalone PowerShell publisher for *Atlassian Confluence Builder for Sphinx*.
|
|
|
|
The following is a sample manifest generated from the default sample:
|
|
|
|
```
|
|
{
|
|
"Pages": [
|
|
{
|
|
"Title": "Default Sample~",
|
|
"Ref": "pages/Default+Sample~.xml"
|
|
},
|
|
{
|
|
"Title": "Cats",
|
|
"Ref": "pages/Cats.xml",
|
|
"AncestorTitle": "Default Sample~"
|
|
}
|
|
],
|
|
"Attachments": [
|
|
{
|
|
"Name": "pexels-just-a-couple-photos-3777622.jpg",
|
|
"ContainerPageTitle": "Cats",
|
|
"MimeType": "image/jpeg",
|
|
"Ref": "attachments/pexels-just-a-couple-photos-3777622.jpg"
|
|
},
|
|
{
|
|
"Name": "pexels-sami-aksu-14356302.jpg",
|
|
"ContainerPageTitle": "Cats",
|
|
"MimeType": "image/jpeg",
|
|
"Ref": "attachments/pexels-sami-aksu-14356302.jpg"
|
|
},
|
|
{
|
|
"Name": "objects.inv",
|
|
"ContainerPageTitle": "Default Sample~",
|
|
"MimeType": "application/octet-stream",
|
|
"Ref": "attachments/objects.inv"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
> **NOTE**: The manifest's schema is currently part of the
|
|
[PSConfluencePublisher](https://bitbucket.org/victorykit/psconfluencepublisher)
|
|
|
|
## Installing
|
|
|
|
You can install this extension via PyPI (through pip):
|
|
|
|
```
|
|
python3 -m pip install victorykit-xconfluencebuilder
|
|
```
|
|
|
|
or via the sources by cloning the repository (then changing into the directory),
|
|
and also using pip
|
|
|
|
```
|
|
$ git clone https://bitbucket.org/victorykit/xconfluencebuilder.git
|
|
...
|
|
$ python3 -m pip install .
|
|
```
|
|
|
|
## Usage
|
|
|
|
In addition to the basic configuration outlined here, you can find a usage
|
|
example under `samples/`.
|
|
|
|
* Register the extension sphinxcontrib.confluencebuilder in the project's
|
|
configuration script (conf.py):
|
|
|
|
```
|
|
extensions = [
|
|
'xconfluencebuilder'
|
|
]
|
|
```
|
|
|
|
* Run sphinx-build with the builder confluence:
|
|
|
|
```
|
|
sphinx-build -b xconfluence . _build/confluence -E -a
|
|
(or)
|
|
python -m sphinx -b xconfluence . _build/confluence -E -a
|
|
```
|
|
|
|
Afterwards, archive the output directory and use it for interchange with an
|
|
external publisher like the aforementioned
|
|
[PSConfluencePublisher](https://bitbucket.org/victorykit/psconfluencepublisher).
|
|
|
|
More information on the usage of this extension can be obtained from the
|
|
extension's documentation this is a drop-in for:
|
|
|
|
> [Atlassian Confluence Builder for Sphinx Tutorial](https://sphinxcontrib-confluencebuilder.readthedocs.io/tutorial)
|
|
|
|
## Configuration
|
|
|
|
In addition to the configuration parameters provided by
|
|
`sphinxcontrib.confluencebuilder`, the following parameters are available:
|
|
|
|
* `xconfluence_outdir` - base directory for archive output (default:
|
|
`{outdir}/confluence.out`)
|
|
* `xconfluence_manifest_basename` - basename of the asset manifest
|
|
|
|
The following `confluencebuilder` configuration parameters are not available:
|
|
|
|
* `confluence_publish_dry_run` (as if set to `False`)
|
|
|
|
The `confluence_publish` parameter must still however be set (to `True`), as
|
|
well as all other configuration parameters which would be required for a minimal
|
|
configuration of `confluencebuilder`. Please refer to [confluencebuilder
|
|
documentation](https://sphinxcontrib-confluencebuilder.readthedocs.io/tutorial)
|
|
on how to do so.
|
|
|
|
## Testing
|
|
|
|
We're patching/mocking a couple of things of the original extension, to make
|
|
this work. Writing proper unit tests for this would take some time to figure out.
|
|
We'll discuss this with the original author of the extension.
|
|
|
|
## Issue Tracking
|
|
|
|
Will be provided shortly.
|