Licensing

.github/workflows/publish-to-pypi.yml

@@ -5,22 +5,33 @@ on: push
 jobs:
   build-n-publish:
     name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     environment:
       name: pypi
       url: https://pypi.org/p/confluence.md
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python 3.9
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: 3.9
-    - name: Install pypa/build
+    - name: Install pip
+      run: python -m pip install --upgrade pip --user
+    - name: Install pytest
+      run: python -m pip install -r requirements.txt --user
+    - name: Run tests
+      shell: bash
+      env:
+        CONFLUENCE_USER: ${{ secrets.CONFLUENCE_USER }}
+        CONFLUENCE_TOKEN: ${{ secrets.CONFLUENCE_TOKEN }}
       run: >-
-        python -m
-        pip install
-        build
-        --user
+        pytest
+        -c "import src.tests.test_confluencemd"
+        --user="$CONFLUENCE_USER"
+        --token="$CONFLUENCE_TOKEN"
+        -vv
+    - name: Install pypi/build
+      run: python -m pip install build --user
     - name: Build a binary wheel and a source tarball
       run: >-
         python -m
@@ -32,10 +43,10 @@ jobs:
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
         skip-existing: true
-        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
         repository-url: https://test.pypi.org/legacy/
+        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
     - name: Publish distribution 📦 to PyPI
       if: startsWith(github.ref, 'refs/tags')
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
-        password: ${{ secrets.PYPI_API_TOKEN }}
+        password: ${{ secrets.TEST_PYPI_API_TOKEN }}

README.md

@@ -15,7 +15,7 @@ It's as easy as:
 $ pip install confluence.md
 ```
 
-## How to use it?
+## How to use it in command-line?
 
 Markdown to Confluence
 
@@ -62,14 +62,18 @@ To create Atlassian API Token go to [api-tokens](https://id.atlassian.com/manage
 - `--add_meta`              adds metadata to .md file for easy editing
 - `--add_info`              adds info panel **automatic content** do not edit on top of the page
 - `--add_label` `ADD_LABEL` adds label to page
+- `--convert_jira`          convert all Jira links to issue snippets (either short [KEY-ID] format or full URL)
+                            **note**: this options works only in Cloud instances with [Smart Issue for Confluence](https://marketplace.atlassian.com/plugins/smart-issue-view-for-confluence) installed
 - `-v`, `--verbose`         verbose mode
 - `-q`, `--quiet`           quiet mode
 
 **required auth parameters:**
 
 - `-u` `USER`, `--user` `USER`    Atlassian username/email
 - `-t` `TOKEN`, `--token` `TOKEN` Atlassian API token
+- `-p` `PWD`, `--password` `PWD`  Atlassian password (used in on-prem instances)
 - `-l` `URL`, `--url` `URL`       Atlassian instance URL
+- `-n`, `--no_verify_ssl`         Don't verify SSL cert in on-prem instances
 
 **create page parameters:**
 
@@ -79,4 +83,21 @@ To create Atlassian API Token go to [api-tokens](https://id.atlassian.com/manage
 
 **update page arguments:**
 
--  `--page_id` `PAGE_ID`     define (or override) page id while updating a page
+-  `--page_id` `PAGE_ID`     define (or override) page id while updating a page
+
+## How to use it in a Python script?
+
+ConfluenceMD wasn't designed to be used this way, but it's fairly simple to embed
+it in a Python script. See this example:
+
+```python
+from md2cf.utils.confluencemd import ConfluenceMD
+conf_md = ConfluenceMD(username=user,
+                       md_file=md_file,
+                       token=token,
+                       url=url,
+                       convert_jira=convert_jira)
+conf_md.create_new("page_id", "title")
+# or
+conf_md.update_existing("page_id")
+```

conftest.py

@@ -0,0 +1,24 @@
+import pytest
+
+# pylint: disable=missing-function-docstring
+
+def pytest_addoption(parser):
+    parser.addoption("--user", action="store", required=True,
+            help="Atlassian username/email")
+    parser.addoption("--token", action="store", required=True,
+            help="Atlassian API token (used in cloud instances)")
+    parser.addoption("--url", action="store", required=False,
+            default="https://dirtyagile.atlassian.net/wiki/",
+            help="Atlassian instance URL")
+
+@pytest.fixture(scope="class")
+def user(request):
+    return request.config.getoption("--user")
+
+@pytest.fixture(scope="class")
+def token(request):
+    return request.config.getoption("--token")
+
+@pytest.fixture(scope="class")
+def url(request):
+    return request.config.getoption("--url")

requirements.txt

@@ -2,3 +2,4 @@ atlassian-python-api>=3.41.3
 coloredlogs>=15.0.1
 markdown2>=2.4.10
 termcolor>=2.3.0
+pytest>=8.1.1

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = confluence.md
-version = 0.3.2
+version = 0.4.1
 author = Szymon Nieradka
 description = Markdown to Confluence - upload any .md files to your Confluence cloud page
 long_description = file: README.md
@@ -18,7 +18,7 @@ classifiers =
     Programming Language :: Python :: 3.8
     Programming Language :: Python :: 3.9
     Programming Language :: Python :: 3.10
-    Development Status :: 4 - Beta
+    Development Status :: 5 - Production/Stable
     Environment :: Console
     Intended Audience :: Developers
     Intended Audience :: Information Technology

src/md2cf/main.py

@@ -1,4 +1,9 @@
 #!/usr/bin/env python3
+"""
+confluence.md
+Push markdown files straight to a Confluence page.
+"""
+
 import sys
 import argparse
 from argparse import RawTextHelpFormatter
@@ -9,11 +14,12 @@
 ACTIONS = {}
 
 def register_action(function):
+    """Register command line action function decorator"""
     ACTIONS[function.__name__] = function.__doc__
     def wrapper(args):
         headline(function.__doc__)
         function(args)
-        headline("End " + function.__name__, True)
+        headline("End " + function.__name__)
     return wrapper
 
 def init_confluence(args):
@@ -40,7 +46,7 @@ def create(args):
     assert args.url, ("No --url parameter is provided, gave up")
 
     confluence = init_confluence(args)
-    confluence.create_page(args.parent_id, args.title, args.overwrite)
+    confluence.create_new(args.parent_id, args.title, args.overwrite)
 
 def main():
     """Markdown to Confluence
@@ -125,7 +131,8 @@ def main():
     parser.add_argument("--add_label", action="store",
             help="adds label to page")
     parser.add_argument("--convert_jira", action="store_true",
-            help="convert all Jira links to issue snippets (either short [KEY-ID] format or full URL)")
+            help="convert all Jira links to issue snippets "
+                 "(either short [KEY-ID] format or full URL)")
 
     parser.add_argument("-v", "--verbose", action="store_true",
             help="verbose mode")
@@ -142,6 +149,7 @@ def main():
 
     try:
         globals()[args.action](args)
+    # pylint: disable=broad-exception-caught
     except (RuntimeError, AssertionError, Exception) as error:
         logger.error(error)
         if args.verbose: