Metadata-Version: 2.1
Name: mdtocf
Version: 1.0.10
Summary: Markdown files/directory publishing to Atlassian Confluence
Home-page: https://github.com/olafrv/mdtocf
Author: Olaf Reitmaier Veracierta
Author-email: olafrv@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: astroid (==2.4.1)
Requires-Dist: atlassian-python-api (==1.15.7)
Requires-Dist: certifi (==2020.4.5.1)
Requires-Dist: chardet (==3.0.4)
Requires-Dist: flake8 (==3.8.2)
Requires-Dist: idna (==2.9)
Requires-Dist: importlib-metadata (==1.6.0)
Requires-Dist: isort (==4.3.21)
Requires-Dist: lazy-object-proxy (==1.4.3)
Requires-Dist: mccabe (==0.6.1)
Requires-Dist: mistune (==2.0.0a4)
Requires-Dist: oauthlib (==3.1.0)
Requires-Dist: pickleDB (==0.9.2)
Requires-Dist: pycodestyle (==2.6.0)
Requires-Dist: pyflakes (==2.2.0)
Requires-Dist: Pygments (==2.6.1)
Requires-Dist: pylint (==2.5.2)
Requires-Dist: requests (==2.23.0)
Requires-Dist: requests-oauthlib (==1.3.0)
Requires-Dist: six (==1.15.0)
Requires-Dist: toml (==0.10.1)
Requires-Dist: typed-ast (==1.4.1)
Requires-Dist: urllib3 (==1.25.9)
Requires-Dist: wrapt (==1.12.1)
Requires-Dist: zipp (==3.1.0)

# Requirements

This Python package has been tested and designed for:

* [Ubuntu 18.04 LTS](https://releases.ubuntu.com/)
* [Python 3.7.5](https://docs.python.org/3/) and several python libraries:
  * [PickelDB v0.9](https://pythonhosted.org/pickleDB/)
  * [Mistune v2.0 Markdown Parser](https://mistune.readthedocs.io/en/latest/)
  * [Atlassian Python API v1.5](https://atlassian-python-api.readthedocs.io/)

Please see [requirements.txt](https://github.com/olafrv/mdtocf/blob/master/requirements.txt)
for specific python packages/modules versions required.

# Missing Features (Todo)

* Attachments (e.g. images, pdf, etc.)

# Install

Download the package and prepare Python environment:

```shell
git clone "https://github.com/olafrv/mdtocf.git"
cd mdtocf
sudo apt install -y python3.7 python3-pip  # Option 1: Install Python at system level
make virtualenv                            # Option 2: Create a Python virtual environment
```

Install the package for its use:

**Note:** If you skip virtual environment you should ensure using python >= 3.7

```shell
source venv/bin/activate         # Use python virtual environment (Optional)
make install                     # Option 1: Use local package in ./mdtocf
make install-pypi                # Option 2: Install package from PyPI
mkdir -p ~/dbs                   # Create temporal database directory
deactivate                       # Deactivate virtual environment (Optional)
```

See an example code in [mdtocf.py](https://github.com/olafrv/mdtocf/blob/master/mdtocf/mdtocf.py)
and the target *test-publish* inside [Makefile](https://github.com/olafrv/mdtocf/blob/master/mdtocf/Makefile)
show some parameters examples.

# Publish using local script

**Note:** If you skip virtual environment you should ensure using python >= 3.7

```shell
source venv/bin/activate               # Use python virtual environment (Optional)
export PYTHON=python                   # Virtual Environment (Default, after 'source')
#export PYTHON=venv/bin/python         # Virtual Environment (Default, without 'source')       
#export PYTHON=venv/bin/python3.7      # Virtual Environment (Default = 3.7, without 'source')
#export PYTHON=/usr/bin/python3.7      # Use system level Python (without virtual environment)
${PYTHON} -m mdtocf.mdtocf --help
${PYTHON} -m mdtocf.mdtocf \ 
    --confluenceUsername "olafrv@gmail.com" \
    --confluenceApiToken "****************" \
    --confluenceUrl "https://olafrv.atlassian.net" \
    --confluenceSpace "TEST" \
    --confluenceParentPageId "33114" \
    --confluencePageTitlePrefix "[Test] " \
    --markdownDir ./examples \
    --db ~/dbs/examples.db
deactivate                       # Deactivate virtual environment (Optional)
```

# Publish using Docker (Image locally built)

```shell
make docker
docker run --rm -it mdtocf --help
docker run --rm -it \
    --mount type=bind,source="$(pwd)"/examples,target=/mdtocf/examples \
    --mount type=bind,source=~/dbs,target=/mdtocf/dbs \
    mdtocf \
    --confluenceUsername "olafrv@gmail.com" \
    --confluenceApiToken "****************" \
    --confluenceUrl "https://olafrv.atlassian.net"   \
    --confluenceSpace "TEST" \
    --confluenceParentPageId "33114" \
    --confluencePageTitlePrefix "[Test] " \
    --markdownDir "./examples" \
    --db ~/dbs/examples.db
```

# Publish using Docker (Image downloaded from Github's Packages)

```shell
# Check <VERSION> in https://github.com/olafrv/mdtocf/packages 
export IMAGE=docker.pkg.github.com/olafrv/mdtocf/mdtocf:<VERSION> 
docker run --rm -it $IMAGE --help
docker run --rm -it \
    --mount type=bind,source="$(pwd)"/examples,target=/mdtocf/examples \
    --mount type=bind,source=~/dbs,target=/mdtocf/dbs \
    $IMAGE
    --confluenceUsername "olafrv@gmail.com" \
    --confluenceApiToken "****************" \
    --confluenceUrl "https://olafrv.atlassian.net"   \
    --confluenceSpace "TEST" \
    --confluenceParentPageId "33114" \
    --confluencePageTitlePrefix "[Test] " \
    --markdownDir ./examples \
    --db ~/dbs/examples.db
```

# Output and Results

Output:
```
UPD => Title: [Test] Folder A
Can't find '[Test] Folder A' page on the https://olafrv.atlassian.net/wiki!
IDX => Title: [Test] Folder B
Can't find '[Test] Folder B' page on the https://olafrv.atlassian.net/wiki!
UPD => Title: [Test] 1
Can't find '[Test] 1' page on the https://olafrv.atlassian.net/wiki!
UPD => Title: [Test] Page AA
Can't find '[Test] Page AA' page on the https://olafrv.atlassian.net/wiki!
UPD => Title: [Test] Example Page
Can't find '[Test] Example Page' page on the https://olafrv.atlassian.net/wiki!
```
The *"Can't find..."* means *"not found but creating..."* (Python Atlassian API).

## Results in Confluence

Rendering and publishing **./examples** produce the following final result in Confluence:

![Result in Confluence](https://raw.githubusercontent.com/olafrv/mdtocf/master/examples/example.png)

## About Markdown Compatibility

This scripts depends on [Mistune v2 Markdown Parser](https://mistune.readthedocs.io/en/latest/),
compatible with [CommonMark](https://spec.commonmark.org)

The (optional) metadata heading in markdown (.md) files likes the one which follows below used by [Hugo](https://gohugo.io/getting-started/quick-start/), it is not part of CommonMarkdown standard, but just a popular way of specify in YAML markdown metadata usable for external tools.
```yaml
title: My Page Title
date: 2019-03-26T08:47:11+01:00
draft: true
chapter: true
kind: index
```
It is parsed and partially used by this script to organize the content in
Attlasian Confluence. A test for this can be run:

```shell
make test-re
```

# References

## Markdown

* https://spec.commonmark.org
* https://spec.commonmark.org/dingus/

## Mistune v2

* https://github.com/lepture/mistune
* https://mistune.readthedocs.io/en/latest/

## Python v3

* https://docs.python.org/3/
* https://docs.python.org/3/howto/regex.html
* https://pypi.org/project/atlassian-python-api/
* https://atlassian-python-api.readthedocs.io/confluence.html

## Confluence and Storage Format (Cloud API)

* https://developer.atlassian.com/cloud/confluence/rest/
* https://confluence.atlassian.com/doc/confluence-server-documentation-135922.html
* https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html
* https://confluence.atlassian.com/doc/macros-139387.html
* https://confluence.atlassian.com/conf59/code-block-macro-792499083.html
* https://confluence.atlassian.com/confkb/how-to-get-confluence-page-id-648380445.html
* https://confluence.atlassian.com/doc/delete-or-restore-a-page-139429.html


