markdown-to-confluence 0.2.0__tar.gz → 0.2.2__tar.gz

{markdown_to_confluence-0.2.0 → markdown_to_confluence-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: markdown-to-confluence
-Version: 0.2.0
+Version: 0.2.2
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -51,7 +51,7 @@ This Python package
 * Image references (uploaded as Confluence page attachments)
 * Tables
 * [Table of contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents)
-* [Admonitions](https://python-markdown.github.io/extensions/admonition/) and [alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
+* [Admonitions](https://python-markdown.github.io/extensions/admonition/) and alert boxes in [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) and [GitLab](https://docs.gitlab.com/ee/development/documentation/styleguide/#alert-boxes)
 * [Collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
 * [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images)
 
@@ -144,21 +144,28 @@ Provide generated-by prompt text in the Markdown file with a tag:
 
 Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes precedence.
 
+### Ignoring files
+
+Skip files in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax of [fnmatch](https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch). Specifically, `?` matches any single character, and `*` matches zero or more characters. For example, use `up-*.md` to exclude Markdown files that start with `up-`. Lines that start with `#` are treated as comments.
+
+Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
 
 ```sh
-$ python3 -m md2conf sample/example.md
+$ python3 -m md2conf sample/index.md
 ```
 
 Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf [-h] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE]
-               [--generated-by GENERATED_BY] [--no-generated-by] [--render-mermaid] [--no-render-mermaid]
-               [--render-mermaid-format {png,svg}] [--heading-anchors] [--ignore-invalid-url] [--local]
+usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE]
+               [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--generated-by GENERATED_BY] [--no-generated-by]
+               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors]
+               [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
                mdpath
 
 positional arguments:
@@ -166,6 +173,7 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
+  --version             show program's version number and exit
   -d DOMAIN, --domain DOMAIN
                         Confluence organization domain.
   -p PATH, --path PATH  Base path for Confluence (default: '/wiki/').
@@ -188,20 +196,35 @@ options:
   --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
   --ignore-invalid-url  Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.
   --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
+  --headers [KEY=VALUE ...]
+                        Apply custom headers to all Confluence API requests.
+  --webui-links         Enable Confluence Web UI links.
 ```
 
-### Using the docker container
+### Using the Docker container
+
+You can run the Docker container via `docker run` or via `Dockerfile`. Either can accept the environment variables or arguments similar to the Python options. The final argument `./` corresponds to `mdpath` in the command-line utility.
+
+With `docker run`, you can pass Confluence domain, user, API and space key directly to `docker run`:
 
-You can run the docker container via `docker run` or via `Dockerfile`. Either can accept the environment variables or arguments similar to the Python options.  The final argument `./` corresponds to `mdpath` in the command-line utility.
+```sh
+docker run --rm --name md2conf -v $(pwd):/data leventehunyadi/md2conf -d instructure.atlassian.net -u levente.hunyadi@instructure.com -a 0123456789abcdef -s DAP ./
+```
+
+Alternatively, you can use a separate file `.env` to pass these parameters as environment variables:
 
 ```sh
-docker run --rm --name md2conf hunyadi/md2conf -d instructure.atlassian.net -u levente.hunyadi@instructure.com -a 0123456789abcdef -s DAP ./
+docker run --rm --env-file .env --name md2conf -v $(pwd):/data leventehunyadi/md2conf ./
 ```
 
-Note that the entry point for the docker container's base image is `ENTRYPOINT ["python3", "-m", "md2conf"]`.
+In each case, `-v $(pwd):/data` maps the current directory to Docker container's `WORKDIR` such *md2conf* can scan files and directories in the local file system.
+
+Note that the entry point for the Docker container's base image is `ENTRYPOINT ["python3", "-m", "md2conf"]`.
+
+With the `Dockerfile` approach, you can extend the base image:
 
 ```Dockerfile
-FROM hunyadi/md2conf:latest
+FROM leventehunyadi/md2conf:latest
 
 ENV CONFLUENCE_DOMAIN='instructure.atlassian.net'
 ENV CONFLUENCE_PATH='/wiki/'
@@ -215,7 +238,7 @@ CMD ["./"]
 Alternatively,
 
 ```Dockerfile
-FROM hunyadi/md2conf:latest
+FROM leventehunyadi/md2conf:latest
 
 CMD ["-d", "instructure.atlassian.net", "-u", "levente.hunyadi@instructure.com", "-a", "0123456789abcdef", "-s", "DAP", "./"]
 ```

{markdown_to_confluence-0.2.0 → markdown_to_confluence-0.2.2}/README.md

@@ -20,7 +20,7 @@ This Python package
 * Image references (uploaded as Confluence page attachments)
 * Tables
 * [Table of contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents)
-* [Admonitions](https://python-markdown.github.io/extensions/admonition/) and [alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
+* [Admonitions](https://python-markdown.github.io/extensions/admonition/) and alert boxes in [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) and [GitLab](https://docs.gitlab.com/ee/development/documentation/styleguide/#alert-boxes)
 * [Collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
 * [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images)
 
@@ -113,21 +113,28 @@ Provide generated-by prompt text in the Markdown file with a tag:
 
 Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes precedence.
 
+### Ignoring files
+
+Skip files in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax of [fnmatch](https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch). Specifically, `?` matches any single character, and `*` matches zero or more characters. For example, use `up-*.md` to exclude Markdown files that start with `up-`. Lines that start with `#` are treated as comments.
+
+Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
 
 ```sh
-$ python3 -m md2conf sample/example.md
+$ python3 -m md2conf sample/index.md
 ```
 
 Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf [-h] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE]
-               [--generated-by GENERATED_BY] [--no-generated-by] [--render-mermaid] [--no-render-mermaid]
-               [--render-mermaid-format {png,svg}] [--heading-anchors] [--ignore-invalid-url] [--local]
+usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE]
+               [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--generated-by GENERATED_BY] [--no-generated-by]
+               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors]
+               [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
                mdpath
 
 positional arguments:
@@ -135,6 +142,7 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
+  --version             show program's version number and exit
   -d DOMAIN, --domain DOMAIN
                         Confluence organization domain.
   -p PATH, --path PATH  Base path for Confluence (default: '/wiki/').
@@ -157,20 +165,35 @@ options:
   --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
   --ignore-invalid-url  Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.
   --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
+  --headers [KEY=VALUE ...]
+                        Apply custom headers to all Confluence API requests.
+  --webui-links         Enable Confluence Web UI links.
 ```
 
-### Using the docker container
+### Using the Docker container
+
+You can run the Docker container via `docker run` or via `Dockerfile`. Either can accept the environment variables or arguments similar to the Python options. The final argument `./` corresponds to `mdpath` in the command-line utility.
+
+With `docker run`, you can pass Confluence domain, user, API and space key directly to `docker run`:
 
-You can run the docker container via `docker run` or via `Dockerfile`. Either can accept the environment variables or arguments similar to the Python options.  The final argument `./` corresponds to `mdpath` in the command-line utility.
+```sh
+docker run --rm --name md2conf -v $(pwd):/data leventehunyadi/md2conf -d instructure.atlassian.net -u levente.hunyadi@instructure.com -a 0123456789abcdef -s DAP ./
+```
+
+Alternatively, you can use a separate file `.env` to pass these parameters as environment variables:
 
 ```sh
-docker run --rm --name md2conf hunyadi/md2conf -d instructure.atlassian.net -u levente.hunyadi@instructure.com -a 0123456789abcdef -s DAP ./
+docker run --rm --env-file .env --name md2conf -v $(pwd):/data leventehunyadi/md2conf ./
 ```
 
-Note that the entry point for the docker container's base image is `ENTRYPOINT ["python3", "-m", "md2conf"]`.
+In each case, `-v $(pwd):/data` maps the current directory to Docker container's `WORKDIR` such *md2conf* can scan files and directories in the local file system.
+
+Note that the entry point for the Docker container's base image is `ENTRYPOINT ["python3", "-m", "md2conf"]`.
+
+With the `Dockerfile` approach, you can extend the base image:
 
 ```Dockerfile
-FROM hunyadi/md2conf:latest
+FROM leventehunyadi/md2conf:latest
 
 ENV CONFLUENCE_DOMAIN='instructure.atlassian.net'
 ENV CONFLUENCE_PATH='/wiki/'
@@ -184,7 +207,7 @@ CMD ["./"]
 Alternatively,
 
 ```Dockerfile
-FROM hunyadi/md2conf:latest
+FROM leventehunyadi/md2conf:latest
 
 CMD ["-d", "instructure.atlassian.net", "-u", "levente.hunyadi@instructure.com", "-a", "0123456789abcdef", "-s", "DAP", "./"]
 ```

{markdown_to_confluence-0.2.0 → markdown_to_confluence-0.2.2}/markdown_to_confluence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: markdown-to-confluence
-Version: 0.2.0
+Version: 0.2.2
 Summary: Publish Markdown files to Confluence wiki
 Home-page: https://github.com/hunyadi/md2conf
 Author: Levente Hunyadi
@@ -51,7 +51,7 @@ This Python package
 * Image references (uploaded as Confluence page attachments)
 * Tables
 * [Table of contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents)
-* [Admonitions](https://python-markdown.github.io/extensions/admonition/) and [alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
+* [Admonitions](https://python-markdown.github.io/extensions/admonition/) and alert boxes in [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) and [GitLab](https://docs.gitlab.com/ee/development/documentation/styleguide/#alert-boxes)
 * [Collapsed sections](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections)
 * [Mermaid diagrams](https://mermaid.live/) in code blocks (converted to images)
 
@@ -144,21 +144,28 @@ Provide generated-by prompt text in the Markdown file with a tag:
 
 Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes precedence.
 
+### Ignoring files
+
+Skip files in a directory with rules defined in `.mdignore`. Each rule should occupy a single line. Rules follow the syntax of [fnmatch](https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch). Specifically, `?` matches any single character, and `*` matches zero or more characters. For example, use `up-*.md` to exclude Markdown files that start with `up-`. Lines that start with `#` are treated as comments.
+
+Files that don't have the extension `*.md` are skipped automatically. Hidden directories (whose name starts with `.`) are not recursed into.
+
 ### Running the tool
 
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
 
 ```sh
-$ python3 -m md2conf sample/example.md
+$ python3 -m md2conf sample/index.md
 ```
 
 Use the `--help` switch to get a full list of supported command-line options:
 
 ```console
 $ python3 -m md2conf --help
-usage: md2conf [-h] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE]
-               [--generated-by GENERATED_BY] [--no-generated-by] [--render-mermaid] [--no-render-mermaid]
-               [--render-mermaid-format {png,svg}] [--heading-anchors] [--ignore-invalid-url] [--local]
+usage: md2conf [-h] [--version] [-d DOMAIN] [-p PATH] [-u USERNAME] [-a APIKEY] [-s SPACE]
+               [-l {debug,info,warning,error,critical}] [-r ROOT_PAGE] [--generated-by GENERATED_BY] [--no-generated-by]
+               [--render-mermaid] [--no-render-mermaid] [--render-mermaid-format {png,svg}] [--heading-anchors]
+               [--ignore-invalid-url] [--local] [--headers [KEY=VALUE ...]] [--webui-links]
                mdpath
 
 positional arguments:
@@ -166,6 +173,7 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
+  --version             show program's version number and exit
   -d DOMAIN, --domain DOMAIN
                         Confluence organization domain.
   -p PATH, --path PATH  Base path for Confluence (default: '/wiki/').
@@ -188,20 +196,35 @@ options:
   --heading-anchors     Place an anchor at each section heading with GitHub-style same-page identifiers.
   --ignore-invalid-url  Emit a warning but otherwise ignore relative URLs that point to ill-specified locations.
   --local               Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.
+  --headers [KEY=VALUE ...]
+                        Apply custom headers to all Confluence API requests.
+  --webui-links         Enable Confluence Web UI links.
 ```
 
-### Using the docker container
+### Using the Docker container
+
+You can run the Docker container via `docker run` or via `Dockerfile`. Either can accept the environment variables or arguments similar to the Python options. The final argument `./` corresponds to `mdpath` in the command-line utility.
+
+With `docker run`, you can pass Confluence domain, user, API and space key directly to `docker run`:
 
-You can run the docker container via `docker run` or via `Dockerfile`. Either can accept the environment variables or arguments similar to the Python options.  The final argument `./` corresponds to `mdpath` in the command-line utility.
+```sh
+docker run --rm --name md2conf -v $(pwd):/data leventehunyadi/md2conf -d instructure.atlassian.net -u levente.hunyadi@instructure.com -a 0123456789abcdef -s DAP ./
+```
+
+Alternatively, you can use a separate file `.env` to pass these parameters as environment variables:
 
 ```sh
-docker run --rm --name md2conf hunyadi/md2conf -d instructure.atlassian.net -u levente.hunyadi@instructure.com -a 0123456789abcdef -s DAP ./
+docker run --rm --env-file .env --name md2conf -v $(pwd):/data leventehunyadi/md2conf ./
 ```
 
-Note that the entry point for the docker container's base image is `ENTRYPOINT ["python3", "-m", "md2conf"]`.
+In each case, `-v $(pwd):/data` maps the current directory to Docker container's `WORKDIR` such *md2conf* can scan files and directories in the local file system.
+
+Note that the entry point for the Docker container's base image is `ENTRYPOINT ["python3", "-m", "md2conf"]`.
+
+With the `Dockerfile` approach, you can extend the base image:
 
 ```Dockerfile
-FROM hunyadi/md2conf:latest
+FROM leventehunyadi/md2conf:latest
 
 ENV CONFLUENCE_DOMAIN='instructure.atlassian.net'
 ENV CONFLUENCE_PATH='/wiki/'
@@ -215,7 +238,7 @@ CMD ["./"]
 Alternatively,
 
 ```Dockerfile
-FROM hunyadi/md2conf:latest
+FROM leventehunyadi/md2conf:latest
 
 CMD ["-d", "instructure.atlassian.net", "-u", "levente.hunyadi@instructure.com", "-a", "0123456789abcdef", "-s", "DAP", "./"]
 ```

{markdown_to_confluence-0.2.0 → markdown_to_confluence-0.2.2}/markdown_to_confluence.egg-info/SOURCES.txt

@@ -16,10 +16,13 @@ md2conf/api.py
 md2conf/application.py
 md2conf/converter.py
 md2conf/entities.dtd
+md2conf/matcher.py
 md2conf/mermaid.py
 md2conf/processor.py
 md2conf/properties.py
+md2conf/puppeteer-config.json
 md2conf/py.typed
 tests/test_conversion.py
+tests/test_matcher.py
 tests/test_mermaid.py
 tests/test_processor.py

{markdown_to_confluence-0.2.0 → markdown_to_confluence-0.2.2}/md2conf/__init__.py

@@ -5,7 +5,7 @@ Parses Markdown files, converts Markdown content into the Confluence Storage For
 Confluence API endpoints to upload images and content.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 __author__ = "Levente Hunyadi"
 __copyright__ = "Copyright 2022-2024, Levente Hunyadi"
 __license__ = "MIT"

{markdown_to_confluence-0.2.0 → markdown_to_confluence-0.2.2}/md2conf/__main__.py

@@ -2,11 +2,13 @@ import argparse
 import logging
 import os.path
 import sys
+import typing
 from pathlib import Path
-from typing import Optional
+from typing import Any, Literal, Optional, Sequence, Union
 
 import requests
 
+from . import __version__
 from .api import ConfluenceAPI
 from .application import Application
 from .converter import ConfluenceDocumentOptions
@@ -24,12 +26,37 @@ class Arguments(argparse.Namespace):
     loglevel: str
     ignore_invalid_url: bool
     heading_anchors: bool
+    root_page: Optional[str]
     generated_by: Optional[str]
+    render_mermaid: bool
+    diagram_output_format: Literal["png", "svg"]
+    webui_links: bool
+
+
+class KwargsAppendAction(argparse.Action):
+    """Append key-value pairs to a dictionary"""
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: Union[None, str, Sequence[Any]],
+        option_string: Optional[str] = None,
+    ) -> None:
+        try:
+            d = dict(map(lambda x: x.split("="), typing.cast(Sequence[str], values)))
+        except ValueError:
+            raise argparse.ArgumentError(
+                self,
+                f'Could not parse argument "{values}". It should follow the format: k1=v1 k2=v2 ...',
+            )
+        setattr(namespace, self.dest, d)
 
 
 def main() -> None:
     parser = argparse.ArgumentParser()
     parser.prog = os.path.basename(os.path.dirname(__file__))
+    parser.add_argument("--version", action="version", version=__version__)
     parser.add_argument(
         "mdpath", help="Path to Markdown file or directory to convert and publish."
     )
@@ -119,6 +146,20 @@ def main() -> None:
         default=False,
         help="Write XHTML-based Confluence Storage Format files locally without invoking Confluence API.",
     )
+    parser.add_argument(
+        "--headers",
+        nargs="*",
+        required=False,
+        action=KwargsAppendAction,
+        metavar="KEY=VALUE",
+        help="Apply custom headers to all Confluence API requests.",
+    )
+    parser.add_argument(
+        "--webui-links",
+        action="store_true",
+        default=False,
+        help="Enable Confluence Web UI links.",
+    )
 
     args = Arguments()
     parser.parse_args(namespace=args)
@@ -139,9 +180,10 @@ def main() -> None:
         root_page_id=args.root_page,
         render_mermaid=args.render_mermaid,
         diagram_output_format=args.diagram_output_format,
+        webui_links=args.webui_links,
     )
     properties = ConfluenceProperties(
-        args.domain, args.path, args.username, args.apikey, args.space
+        args.domain, args.path, args.username, args.apikey, args.space, args.headers
     )
     if args.local:
         Processor(options, properties).process(args.mdpath)

{markdown_to_confluence-0.2.0 → markdown_to_confluence-0.2.2}/md2conf/api.py

@@ -98,6 +98,10 @@ class ConfluenceAPI:
             session.headers.update(
                 {"Authorization": f"Bearer {self.properties.api_key}"}
             )
+
+        if self.properties.headers:
+            session.headers.update(self.properties.headers)
+
         self.session = ConfluenceSession(
             session,
             self.properties.domain,
@@ -352,6 +356,34 @@ class ConfluenceSession:
             content=typing.cast(str, storage["value"]),
         )
 
+    def get_page_ancestors(
+        self, page_id: str, *, space_key: Optional[str] = None
+    ) -> Dict[str, str]:
+        """
+        Retrieve Confluence wiki page ancestors.
+
+        :param page_id: The Confluence page ID.
+        :param space_key: The Confluence space key (unless the default space is to be used).
+        :returns: Dictionary of ancestor page ID to title, with topmost ancestor first.
+        """
+
+        path = f"/content/{page_id}"
+        query = {
+            "spaceKey": space_key or self.space_key,
+            "expand": "ancestors",
+        }
+        data = typing.cast(Dict[str, JsonType], self._invoke(path, query))
+        ancestors = typing.cast(List[JsonType], data["ancestors"])
+
+        # from the JSON array of ancestors, extract the "id" and "title"
+        results: Dict[str, str] = {}
+        for node in ancestors:
+            ancestor = typing.cast(Dict[str, JsonType], node)
+            id = typing.cast(str, ancestor["id"])
+            title = typing.cast(str, ancestor["title"])
+            results[id] = title
+        return results
+
     def get_page_version(
         self,
         page_id: str,