With Junction you can write and manage your documentation directly in your codebase, using Markdown and your existing Git workflows (pull requests, code review, release branches, etc) and then automatically publish your changes to Confluence. This gives you the best of both worlds: in-repo documentation that fits natively into your development workflows, with the discoverability and centrality of Confluence.
 [](https://pypi.org/project/confluence-junction) 
# Install
Ensure you are using Python 3.8 (or newer); Junction does not work with older versions of Python. Install using `pip`:
```sh
pip install confluence-junction
```
This will install the library and CLI.
In your Python code:
```python
import junction
```
In your shell:
```sh
junction --help
```
# Overview
Junction works by inspecting the changes made on a commit-by-commit basis to your Git repository, and determining what needs to be changed in Confluence to reflect those changes. Junction (currently) expects to manage the entire [space in Confluence](https://confluence.atlassian.com/doc/spaces-139459.html). Thus when using Junction you must tell it which Space to target and update. You must not manually change, create, or modify pages in the target space, or else Junction may be unable to synchronize the state in Git with the state in Confluence.
To allow mixing code (and other items) with markdown files for Junction in a single repository, you can tell Junction a subpath within your repository that functions as the root e.g. all markdown files will be kept in `docs/`. All files should end with the `.md` extension.
The page will gets its title from the file name, and its contents will be translated into Confluence markup. See [this example for what output looks like in Confluence](#output-example).
# Usage
Collect a set of credentials that Junction will use to login to Confluence. You will need to create an [API token](https://confluence.atlassian.com/cloud/api-tokens-938839638.html) to use instead of a password. **I recommend you make a dedicated user account with access permissions limited to the space(s) you want to manage with Junction**.
In your git repository, create a folder structure and markdown files you would like to publish. Commit those changes.
```
.
├── (your code and other files)
└── docs/
├── Welcome.md
├── Installation.md
└── Advanced Usage
| ├── Airflow.md
| ├── Visual Studio Online.md
| ├── Atlassian Bamboo.md
| └── GitHub Actions.md
└── Credits.md
```
Junction is designed as a library, and also provides "helpers" that make using it in different contexts easy (in particularly, as part of automated workflows e.g. in post-push builds).
The simplest way to use Junction is the included CLI `junction`:
```sh
junction -s "SPACE_KEY" -c "https://jihugh.atlassian.net/wiki/rest/api" -u "account@email.com" -p "YOUR_API_ACCESS_TOKEN" delta --content-path docs/ HEAD~5 master
```
> You can put the API, user, and key into environment variables to avoid specifying them for every invocation of Junction. The variables are `CONFLUENCE_API`, `CONFLUENCE_API_USER`, and `CONFLUENCE_API_KEY` respectively.
The CLI is fully documented, so make use of the `--help` option to navigate all of the configuration options.
### Dry Run
You can check what the `junction` CLI will do to your space without actually uploading the changes to Confluence by using the `--dry-run` flag.
### Python Library
Using the Python library will let you create your own wrappers and tools, for example an AirFlow DAG. Here is an equivalent of the above CLI usage in Python:
```python
from pathlib import Path
from git import Repo
from junction.git import find_commits_on_branch_after, filter_modifications_to_folder, get_modifications
from junction.delta import Delta
from junction.confluence import Confluence
cf = Confluence("https://jihugh.atlassian.net/wiki/rest/api", "account@email.com", "YOUR_API_ACCESS_TOKEN", "SPACE_KEY")
repo = Repo("."). # current working directory must be the root of the Git repository for this to work
commits = find_commits_on_branch_after("master", "HEAD~5", repo)
deltas = [Delta.from_modifications(filter_modifications_to_folder(get_modification(commit), Path("docs/"))) for commit in commits]
for delta in deltas:
delta.execute(cf)
```
# Output Example
The following markdown sample, stored in `Sample.md`, produces a page in Confluence that looks like [this](https://github.com/HUU/Junction/blob/master/docs/example_output.png?raw=true). This shows all of the major supported features and markup. It is intentionally very similar to GitHub-style markdown, with some extensions and differences to account for Confluence-specific features.
# Text
It's very easy to make some words **bold** and other words *italic* with Markdown. You can even [link to Google!](http://google.com).
Even some fancy formats like Subscripts~with tilde~ and Superscripts^with caret^.
# Lists
Sometimes you want numbered lists:
1. One
2. Two
3. Three
Sometimes you want bullet points:
* Start a line with a star
* Profit!
Alternatively,
- Dashes work just as well
- And if you have sub points, put four spaces before the dash or star:
- Like this
- And this
# Headers
Sometimes it's useful to have different levels of headings to structure your documents. Start lines with a `#` to create headings. Multiple `##` in a row denote smaller heading sizes.
### This is a third-tier heading
You can use one `#` all the way up to `######` six for different heading sizes.
# Blockquotes
If you'd like to quote someone, use the > character before the line:
> Coffee. The finest organic suspension ever devised... I beat the Borg with it.
> - Captain Janeway
# Code
You can embed `inline code fragments` by surrounding it in backticks. For longer blocks of
code, use "code fencing":
```
if (isAwesome){
return true
}
```
And if you'd like to use syntax highlighting, include the language:
```php
<?php
echo "Hello World"
?>
```
# Tables
You can create tables by assembling a list of words and dividing them with hyphens `-` (for the first row), and then separating each column with a pipe `|`:
First Header | Second Header
------------ | -------------
Content from cell 1 | Content from cell 2
Content in the first column | Content in the second column
# Confluence-specific Elements
You can link to other wiki pages by referencing their page titles. Use normal link syntax, but prepend a `&` like &[this](Page Title).
## Supported Macros
You can embed the Confluence child pages macro by placing it on its own line:
:include-children:
...or the table of contents macro:
:include-toc:
## Status Blocks
You can create Confluence status macros (colored pills), including in the middle of the line &status-green:like this;
&status-green:Complete; &status-yellow:In Progress; &status-grey:Planning; &status-red:Failed; &status-blue:Unknown; &status-purple:Cancelled;
## Info Panels
Info: You can create info panels by prepending a paragraph with one of `Info:`, `Warning:`, `Error:`, or `Success:`.
Warning: The prefix will be removed from the contents.
Error: You cannot put multiple paragraphs inside an info panel, just a single block of text
like this.
Success: like other block elements, each info panel must be located on its own line (fenced between two new lines).
# Contributing
This is a hobby project of mine, and I may not be able to work on it immediately upon request. If you are interested in contributing, feel free to open a PR by following [the contribution guidelines](https://github.com/HUU/Junction/blob/master/CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/HUU/Junction",
"name": "confluence-junction",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "confluence, markdown, git, sync, convert",
"author": "HUU",
"author_email": "readabook123@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/df/07/ba5ba367a67cd2229687c62783aec25adb78ea4d731f3a6026a78dbf8aee/confluence_junction-0.1.2.tar.gz",
"platform": null,
"description": "\n\nWith Junction you can write and manage your documentation directly in your codebase, using Markdown and your existing Git workflows (pull requests, code review, release branches, etc) and then automatically publish your changes to Confluence. This gives you the best of both worlds: in-repo documentation that fits natively into your development workflows, with the discoverability and centrality of Confluence.\n\n [](https://pypi.org/project/confluence-junction) \n\n# Install\n\nEnsure you are using Python 3.8 (or newer); Junction does not work with older versions of Python. Install using `pip`:\n```sh\npip install confluence-junction\n```\nThis will install the library and CLI.\nIn your Python code:\n```python\nimport junction\n```\nIn your shell:\n```sh\njunction --help\n```\n\n# Overview\n\nJunction works by inspecting the changes made on a commit-by-commit basis to your Git repository, and determining what needs to be changed in Confluence to reflect those changes. Junction (currently) expects to manage the entire [space in Confluence](https://confluence.atlassian.com/doc/spaces-139459.html). Thus when using Junction you must tell it which Space to target and update. You must not manually change, create, or modify pages in the target space, or else Junction may be unable to synchronize the state in Git with the state in Confluence.\n\nTo allow mixing code (and other items) with markdown files for Junction in a single repository, you can tell Junction a subpath within your repository that functions as the root e.g. all markdown files will be kept in `docs/`. All files should end with the `.md` extension.\n\nThe page will gets its title from the file name, and its contents will be translated into Confluence markup. See [this example for what output looks like in Confluence](#output-example).\n\n# Usage\n\nCollect a set of credentials that Junction will use to login to Confluence. You will need to create an [API token](https://confluence.atlassian.com/cloud/api-tokens-938839638.html) to use instead of a password. **I recommend you make a dedicated user account with access permissions limited to the space(s) you want to manage with Junction**.\n\nIn your git repository, create a folder structure and markdown files you would like to publish. Commit those changes.\n```\n.\n\u251c\u2500\u2500 (your code and other files)\n\u2514\u2500\u2500 docs/\n \u251c\u2500\u2500 Welcome.md\n \u251c\u2500\u2500 Installation.md\n \u2514\u2500\u2500 Advanced Usage\n | \u251c\u2500\u2500 Airflow.md\n | \u251c\u2500\u2500 Visual Studio Online.md\n | \u251c\u2500\u2500 Atlassian Bamboo.md\n | \u2514\u2500\u2500 GitHub Actions.md\n \u2514\u2500\u2500 Credits.md\n```\n\nJunction is designed as a library, and also provides \"helpers\" that make using it in different contexts easy (in particularly, as part of automated workflows e.g. in post-push builds).\n\nThe simplest way to use Junction is the included CLI `junction`:\n```sh\njunction -s \"SPACE_KEY\" -c \"https://jihugh.atlassian.net/wiki/rest/api\" -u \"account@email.com\" -p \"YOUR_API_ACCESS_TOKEN\" delta --content-path docs/ HEAD~5 master\n```\n> You can put the API, user, and key into environment variables to avoid specifying them for every invocation of Junction. The variables are `CONFLUENCE_API`, `CONFLUENCE_API_USER`, and `CONFLUENCE_API_KEY` respectively.\n\nThe CLI is fully documented, so make use of the `--help` option to navigate all of the configuration options.\n\n### Dry Run\n\nYou can check what the `junction` CLI will do to your space without actually uploading the changes to Confluence by using the `--dry-run` flag.\n\n\n\n### Python Library\n\nUsing the Python library will let you create your own wrappers and tools, for example an AirFlow DAG. Here is an equivalent of the above CLI usage in Python:\n\n```python\nfrom pathlib import Path\nfrom git import Repo\nfrom junction.git import find_commits_on_branch_after, filter_modifications_to_folder, get_modifications\nfrom junction.delta import Delta\nfrom junction.confluence import Confluence\n\ncf = Confluence(\"https://jihugh.atlassian.net/wiki/rest/api\", \"account@email.com\", \"YOUR_API_ACCESS_TOKEN\", \"SPACE_KEY\")\nrepo = Repo(\".\"). # current working directory must be the root of the Git repository for this to work\n\ncommits = find_commits_on_branch_after(\"master\", \"HEAD~5\", repo)\ndeltas = [Delta.from_modifications(filter_modifications_to_folder(get_modification(commit), Path(\"docs/\"))) for commit in commits]\n\nfor delta in deltas:\n delta.execute(cf)\n```\n\n# Output Example\n\nThe following markdown sample, stored in `Sample.md`, produces a page in Confluence that looks like [this](https://github.com/HUU/Junction/blob/master/docs/example_output.png?raw=true). This shows all of the major supported features and markup. It is intentionally very similar to GitHub-style markdown, with some extensions and differences to account for Confluence-specific features.\n\n # Text\n\n It's very easy to make some words **bold** and other words *italic* with Markdown. You can even [link to Google!](http://google.com).\n Even some fancy formats like Subscripts~with tilde~ and Superscripts^with caret^.\n\n # Lists\n\n Sometimes you want numbered lists:\n\n 1. One\n 2. Two\n 3. Three\n\n Sometimes you want bullet points:\n\n * Start a line with a star\n * Profit!\n\n Alternatively,\n\n - Dashes work just as well\n - And if you have sub points, put four spaces before the dash or star:\n - Like this\n - And this\n\n # Headers\n\n Sometimes it's useful to have different levels of headings to structure your documents. Start lines with a `#` to create headings. Multiple `##` in a row denote smaller heading sizes.\n\n ### This is a third-tier heading\n\n You can use one `#` all the way up to `######` six for different heading sizes.\n\n # Blockquotes\n\n If you'd like to quote someone, use the > character before the line:\n\n > Coffee. The finest organic suspension ever devised... I beat the Borg with it.\n > - Captain Janeway\n\n # Code\n\n You can embed `inline code fragments` by surrounding it in backticks. For longer blocks of\n code, use \"code fencing\":\n\n ```\n if (isAwesome){\n return true\n }\n ```\n\n And if you'd like to use syntax highlighting, include the language:\n\n ```php\n <?php\n echo \"Hello World\"\n ?>\n ```\n\n # Tables\n\n You can create tables by assembling a list of words and dividing them with hyphens `-` (for the first row), and then separating each column with a pipe `|`:\n\n First Header | Second Header\n ------------ | -------------\n Content from cell 1 | Content from cell 2\n Content in the first column | Content in the second column\n\n # Confluence-specific Elements\n\n You can link to other wiki pages by referencing their page titles. Use normal link syntax, but prepend a `&` like &[this](Page Title).\n\n ## Supported Macros\n\n You can embed the Confluence child pages macro by placing it on its own line:\n\n :include-children:\n\n ...or the table of contents macro:\n\n :include-toc:\n\n ## Status Blocks\n\n You can create Confluence status macros (colored pills), including in the middle of the line &status-green:like this;\n\n &status-green:Complete; &status-yellow:In Progress; &status-grey:Planning; &status-red:Failed; &status-blue:Unknown; &status-purple:Cancelled;\n\n ## Info Panels\n\n Info: You can create info panels by prepending a paragraph with one of `Info:`, `Warning:`, `Error:`, or `Success:`.\n\n Warning: The prefix will be removed from the contents.\n\n Error: You cannot put multiple paragraphs inside an info panel, just a single block of text\n like this.\n\n Success: like other block elements, each info panel must be located on its own line (fenced between two new lines).\n\n# Contributing\n\nThis is a hobby project of mine, and I may not be able to work on it immediately upon request. If you are interested in contributing, feel free to open a PR by following [the contribution guidelines](https://github.com/HUU/Junction/blob/master/CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Publish to and manage Confluence spaces with markdown files tracked in Git.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/HUU/Junction",
"Repository": "https://github.com/HUU/Junction"
},
"split_keywords": [
"confluence",
" markdown",
" git",
" sync",
" convert"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4a2da2c6660d576f571109f27b2b1698e5b506c2b735e058bf625b52533d9737",
"md5": "c5cb272f622802828f9a6d472f85ecfc",
"sha256": "83565117f51ee1b91cc77af38d7e59dc49fed86f815ae8288692da89a3e77ef1"
},
"downloads": -1,
"filename": "confluence_junction-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5cb272f622802828f9a6d472f85ecfc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 35323,
"upload_time": "2024-05-16T05:51:29",
"upload_time_iso_8601": "2024-05-16T05:51:29.558803Z",
"url": "https://files.pythonhosted.org/packages/4a/2d/a2c6660d576f571109f27b2b1698e5b506c2b735e058bf625b52533d9737/confluence_junction-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "df07ba5ba367a67cd2229687c62783aec25adb78ea4d731f3a6026a78dbf8aee",
"md5": "4333701de01ca7d9eccecfaf5036ac89",
"sha256": "0ab818178430b1c0cb164452d8002bdde64f10058a596556c35e991094bed356"
},
"downloads": -1,
"filename": "confluence_junction-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "4333701de01ca7d9eccecfaf5036ac89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 31352,
"upload_time": "2024-05-16T05:51:30",
"upload_time_iso_8601": "2024-05-16T05:51:30.948503Z",
"url": "https://files.pythonhosted.org/packages/df/07/ba5ba367a67cd2229687c62783aec25adb78ea4d731f3a6026a78dbf8aee/confluence_junction-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-16 05:51:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HUU",
"github_project": "Junction",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "confluence-junction"
}
JSON
