semvec/pypi-packages huggingface dataset:
con2sphx 1.0
Convert a Confluence export to Sphinx
License: Apache2

# Convert Confluence to Sphinx

This utility assists in converting Confluence content to a Sphinx project. Specifically, once you have a
Confluence HTML export that has been [converted to Markdown](https://github.com/meridius/confluence-to-markdown),
run this utility against the converted source to move documents into a directory structure that mirrors
the confluence page hierarchy as well as generating the toctree directives necessary to correctlly publish
back to confluence.

To run:

```shell
./con2sphx <source-dr> <target-dir>
```

## Notes

When exporting from confluence, an `index.md` file is generated that holds the exported page hierarchy in a
nested list. This utility relies on that format, so the `index.md` file should not be edited prior to running 
this utility.

## What it does...

The HTML export from Conflunece dumps the whole tree into a single directory. The con2sphx will create a directory
tree to mirror the page hierarchy from confluence and do some of the requisite fixup automatically. Additionally
it will generate the toctree sections to ensure that the correct page hierarchy is restored upon publication.

There are several other miscellaneous fixups that are performed including: referencing attachement and image links
from the root rather than the current directory and removal of some sections that are added to a given page that are not
present in the Confluence page source, e.g. Comments, Attachment Lists, Change History.

## Step by Step Instructions

0) Prerequisites: Node.js installed, Python installed
1) Use Confluence to export all or a part of your wiki via HTML. 
   ([Export Content...](https://confluence.atlassian.com/doc/export-content-to-word-pdf-html-and-xml-139475.html))
2) Create a working directory and unzip the Confluence export into that directory (sub-dir html)
3) Clone [Confluence to Markdown](https://github.com/meridius/confluence-to-markdown)
4) From within the cloned directory run `npm run start <working-dir>/html <working-dir>/markdown`
5) `pip install con2sphx`
6) Run con2sphx to convert the exported markdown into a MyST, sphinx friendly markdown/dir structure
    `con2sphx <working-dir>/markdown <working-dir>/sphinx`
7) Copy the resultant sphinx friendly markdown into the sphinx project of your choice
8) Use sphinx to build your desired output. **Note:** this will results in a number of warnings that 
    need to be addressed. Some links will be broken due to the directory change (TODO: working on this one).
    Some image links may have sytling, etc. that will required to fix (using Sphinx image directive, TODO: also 
    working on this one), etc.