4 Commits

Author SHA1 Message Date
162cb4a1bb Update variable naming (#7)
Co-authored-by: Nikolai Rodionov <nikolai.rodionov@grandcentrix.net>
Reviewed-on: https://git.badhouseplants.net/allanger/mkdocs-with-confluence/pulls/7
2023-02-28 10:42:32 +00:00
36ae68be6b fix: typo in Readme.md 2023-02-24 17:41:10 +01:00
c3a08433de Update README.md 2023-02-24 17:39:55 +01:00
dba633cccf Plugin shouldn't break the whole build (#6)
Now the whole logic is wrapped by `try`, so if plugin is failed, it won't break the whole build

Also, there were several changes
- Add header_message, so header_warning is still there ("‼️ This page is created automatically, all your changes will be overwritten during the next MKDocs deployment. Do not edit a page here ‼️") when you want to add a custom message
- Add upstream_url, so now there is a link to the original page, if it's provided
- Migrate to default python logging lib

Co-authored-by: Nikolai Rodionov <nikolai.rodionov@grandcentrix.net>
Reviewed-on: https://git.badhouseplants.net/allanger/mkdocs-with-confluence/pulls/6
2023-02-24 16:30:07 +00:00
5 changed files with 125 additions and 92 deletions

View File

@ -7,7 +7,7 @@ venv:
run_example: run_example:
@docker build -t mkdocs-example -f ./example/Dockerfile --build-arg JIRA_PASSWORD=$(shell sops --decrypt ./example/secret.yaml | yq '.JIRA_PASSWORD' ) . @docker build -t mkdocs-example -f ./example/Dockerfile --build-arg MKDOCS_TO_CONFLUENCE_PASSWORD=$(shell sops --decrypt ./example/secret.yaml | yq '.JIRA_PASSWORD' ) .
@docker run -p 8000:8000 mkdocs-example @docker run -p 8000:8000 mkdocs-example
lint: lint:

View File

@ -8,7 +8,9 @@ To enable plugin, you need to set the `MKDOCS_TO_CONFLUENCE` environment variabl
```BASH ```BASH
export MKDOCS_TO_CONFLUENCE=1 export MKDOCS_TO_CONFLUENCE=1
``` ```
By default the dry-run mode is turned off. If you wan't to enable it, you can use the config file, ot the `MKDOCS_TO_CONFLUENCE_DRY_RUN` environment variable By default the dry-run mode is turned off. If you wan't to enable it, you can use the config file, ot the `MKDOCS_TO_CONFLUENCE_DRY_RUN` environment variable
```BASH ```BASH
export MKDOCS_TO_CONFLUENCE_DRY_RUN=1 export MKDOCS_TO_CONFLUENCE_DRY_RUN=1
``` ```
@ -16,13 +18,12 @@ export MKDOCS_TO_CONFLUENCE_DRY_RUN=1
## Setup ## Setup
Install the plugin using pip: Install the plugin using pip:
`pip install mkdocs-with-confluence` `pip install https://github.com/allanger/mkdocs-with-confluence/releases/download/v0.3.1/mkdocs_with_confluence-0.3.1.tar.gz`
Activate the plugin in `mkdocs.yml`: Activate the plugin in `mkdocs.yml`:
```yaml ```yaml
plugins: plugins:
- search
- mkdocs-with-confluence - mkdocs-with-confluence
``` ```
@ -37,12 +38,14 @@ Use following config and adjust it according to your needs:
host_url: https://<YOUR_CONFLUENCE_DOMAIN>/rest/api/content host_url: https://<YOUR_CONFLUENCE_DOMAIN>/rest/api/content
space: <YOUR_SPACE> space: <YOUR_SPACE>
parent_page_name: <YOUR_ROOT_PARENT_PAGE> parent_page_name: <YOUR_ROOT_PARENT_PAGE>
username: <YOUR_USERNAME_TO_CONFLUENCE> username: <YOUR_USERNAME_TO_CONFLUENCE> # JIRA_USERNAME env var can be used
password: <YOUR_PASSWORD_TO_CONFLUENCE> password: <YOUR_PASSWORD_TO_CONFLUENCE> # JIRA_PASSWORD env var can be used
dryrun: true dryrun: true # MKDOCS_TO_CONFLUENCE_DRY_RUN env var can be used
``` header_message: <A_MESSAGE_THAT_WILL_BE_ADDED_TO_EVERY_PAGE>
upstream_url: <URL_OF_YOUR_MKDOCS_INSTANCE>
header_warning: "‼️ This page is created automatically, all you changes will be overwritten during the next MKDocs deployment. Do not edit a page here ‼️"
## Parameters: ```
### Requirements ### Requirements
- md2cf - md2cf

View File

@ -9,9 +9,9 @@ RUN mkdir /out
RUN mv $(find /src/dist -maxdepth 1 -mindepth 1 -name '*tar.gz') /out/mkdocs_with_confluence.tar.gz RUN mv $(find /src/dist -maxdepth 1 -mindepth 1 -name '*tar.gz') /out/mkdocs_with_confluence.tar.gz
FROM BUILDER as common_builder FROM BUILDER as common_builder
ARG MKDOCS_TO_CONFLUENCE_PASSWORD
ENV MKDOCS_TO_CONFLUENCE=true ENV MKDOCS_TO_CONFLUENCE=true
ARG JIRA_PASSWORD ENV MKDOCS_TO_CONFLUENCE_PASSWORD=$MKDOCS_TO_CONFLUENCE_PASSWORD
ENV JIRA_PASSWORD=$JIRA_PASSWORD
RUN pip install mkdocs mkdocs-material RUN pip install mkdocs mkdocs-material
WORKDIR /src WORKDIR /src
COPY ./example /src COPY ./example /src

View File

@ -10,6 +10,8 @@ import mimetypes
import mistune import mistune
import contextlib import contextlib
import time import time
import logging
logger = logging.getLogger('mkdocs')
from time import sleep from time import sleep
from mkdocs.config import config_options from mkdocs.config import config_options
@ -17,14 +19,13 @@ from mkdocs.plugins import BasePlugin
from md2cf.confluence_renderer import ConfluenceRenderer from md2cf.confluence_renderer import ConfluenceRenderer
from os import environ from os import environ
from pathlib import Path from pathlib import Path
from loguru import logger
ENABLE_ENV_VAR = "MKDOCS_TO_CONFLUENCE" ENABLE_ENV_VAR = "MKDOCS_TO_CONFLUENCE"
DRY_RUN_ENV_VAR = "MKDOCS_TO_CONFLUENCE_DRY_RUN" DRY_RUN_ENV_VAR = "MKDOCS_TO_CONFLUENCE_DRY_RUN"
TEMPLATE_BODY = "<p> TEMPLATE </p>"
HEADER_MESSAGE = "‼️ This page is created automatically, all you changes will be overwritten during the next MKDocs deployment. Do not edit a page here ‼️"
SECTION_PAGE_CONTENT = "<p> It's juat a Section Page </p>" TEMPLATE_BODY = "<p> TEMPLATE </p>"
HEADER_WARNING = "‼️ This page is created automatically, all you changes will be overwritten during the next MKDocs deployment. Do not edit a page here ‼️"
SECTION_PAGE_CONTENT = "<p> It's just a Section Page </p>"
# -- I don't know why it's here # -- I don't know why it's here
@contextlib.contextmanager @contextlib.contextmanager
@ -45,10 +46,12 @@ class MkdocsWithConfluence(BasePlugin):
("host_url", config_options.Type(str, default=None)), ("host_url", config_options.Type(str, default=None)),
("space", config_options.Type(str, default=None)), ("space", config_options.Type(str, default=None)),
("parent_page_name", config_options.Type(str, default=None)), ("parent_page_name", config_options.Type(str, default=None)),
("username", config_options.Type(str, default=environ.get("JIRA_USERNAME", None))), ("username", config_options.Type(str, default=environ.get("MKDOCS_TO_CONFLUENCE_USER", None))),
("password", config_options.Type(str, default=environ.get("JIRA_PASSWORD", None))), ("password", config_options.Type(str, default=environ.get("MKDOCS_TO_CONFLUENCE_PASSWORD", None))),
("dryrun", config_options.Type(bool, default=False)), ("dryrun", config_options.Type(bool, default=False)),
("header_message", config_options.Type(str, default=HEADER_MESSAGE)), ("header_message", config_options.Type(str, default=None)),
("upstream_url", config_options.Type(str, default=None)),
("header_warning", config_options.Type(str, default=HEADER_WARNING)),
) )
def __init__(self): def __init__(self):
@ -60,9 +63,11 @@ class MkdocsWithConfluence(BasePlugin):
self.session = requests.Session() self.session = requests.Session()
self.page_attachments = {} self.page_attachments = {}
self.repo_url = None self.repo_url = None
self.header_message = None
self.upstream_url = None
def on_config(self, config): def on_config(self, config):
logger.info(config)
# ------------------------------------------------------ # ------------------------------------------------------
# -- Enable the plugin by setting environment variable # -- Enable the plugin by setting environment variable
# ------------------------------------------------------ # ------------------------------------------------------
@ -88,8 +93,22 @@ class MkdocsWithConfluence(BasePlugin):
if config["repo_url"]: if config["repo_url"]:
self.repo_url = config["repo_url"] self.repo_url = config["repo_url"]
logger.info(f"git url is set to {self.repo_url}") logger.info(f"git url is set to {self.repo_url}")
# ------------------------------------------------------
# -- Set a custom header to add to a confluence page
# ------------------------------------------------------
if self.config["header_message"]:
self.header_message = self.config["header_message"]
logger.info(f"header message is set to {self.header_message}")
# ------------------------------------------------------
# -- Set an upstream url to add to a confluence page
# ------------------------------------------------------
if self.config["upstream_url"]:
self.upstream_url = self.config["upstream_url"]
logger.info(f"upstream url is set to {self.upstream_url}")
def on_files(self, files, config): def on_files(self, files, config):
if self.enabled:
pages = files.documentation_pages() pages = files.documentation_pages()
try: try:
self.flen = len(pages) self.flen = len(pages)
@ -98,8 +117,8 @@ class MkdocsWithConfluence(BasePlugin):
logger.error("no files found to be synced") logger.error("no files found to be synced")
def on_page_markdown(self, markdown, page, config, files): def on_page_markdown(self, markdown, page, config, files):
# TODO: Modify pages here if self.enabled:
logger.warning("TODO: page should be modified in this block") try:
self.session.auth = (self.config["username"], self.config["password"]) self.session.auth = (self.config["username"], self.config["password"])
confluencePageName = page.url[0:-1] confluencePageName = page.url[0:-1]
#.replace("/", "-") #.replace("/", "-")
@ -125,14 +144,22 @@ class MkdocsWithConfluence(BasePlugin):
else: else:
page_name = path page_name = path
logger.info(f"Will create a page {page_name} under the {parent_page}") logger.info(f"Will create a page {page_name} under the {parent_page}")
self.add_page(page_name, parent_id, "<p> I want to make sections pages better: https://git.badhouseplants.net/allanger/mkdocs-with-confluence/issues/2 </p>") self.add_page(page_name, parent_id, SECTION_PAGE_CONTENT)
parent_page = page_name parent_page = page_name
parent_id = self.find_page_id(parent_page) parent_id = self.find_page_id(parent_page)
confluencePageName = parent_page + " " + page.title confluencePageName = parent_page + " " + page.title
new_markdown = markdown new_markdown = markdown
# -- Adding an upstream url
if self.upstream_url:
new_markdown = f">Original page is here: {self.upstream_url}/{page.url}\n\n" + new_markdown
# -- Adding a header message
if self.header_message:
new_markdown = f">{self.header_message}\n\n" + new_markdown
# -- Adding a repo url
if self.repo_url: if self.repo_url:
new_markdown = f">You can edit documentation here: {self.repo_url}\n" + new_markdown new_markdown = f">You can edit documentation here: {self.repo_url}\n\n" + new_markdown
new_markdown = f">{self.config['header_message']}\n\n" + new_markdown # -- Adding a header warning
new_markdown = f">{self.config['header_warning']}\n\n" + new_markdown
# ------------------------------------------------- # -------------------------------------------------
# -- Sync attachments # -- Sync attachments
# ------------------------------------------------- # -------------------------------------------------
@ -164,9 +191,12 @@ class MkdocsWithConfluence(BasePlugin):
self.add_or_update_attachment(confluencePageName, attachment) self.add_or_update_attachment(confluencePageName, attachment)
except Exception as Argument: except Exception as Argument:
logger.warning(Argument) logger.warning(Argument)
except Exception as exp:
logger.error(exp)
return markdown return markdown
def on_post_page(self, output, page, config): def on_post_page(self, output, page, config):
if self.enabled:
logger.info("The author was uploading images here, maybe there was a reason for that") logger.info("The author was uploading images here, maybe there was a reason for that")
def on_page_content(self, html, page, config, files): def on_page_content(self, html, page, config, files):

View File

@ -1,6 +1,6 @@
[tool.poetry] [tool.poetry]
name = "mkdocs-with-confluence" name = "mkdocs-with-confluence"
version = "0.3.0" version = "0.3.2"
description = "MkDocs plugin for uploading markdown documentation to Confluence via Confluence REST API" description = "MkDocs plugin for uploading markdown documentation to Confluence via Confluence REST API"
authors = ["Nikolai Rodionov <allanger@zohomail.com>"] authors = ["Nikolai Rodionov <allanger@zohomail.com>"]
readme = "README.md" readme = "README.md"