path: root/python-confluence-poster.spec

%global _empty_manifest_terminate_build 0
Name:		python-confluence-poster
Version:	1.4.4
Release:	1
Summary:	Script that updates Confluence articles from files written locally
License:	MIT
URL:		https://github.com/VTimofeenko/confluence_poster
Source0:	https://mirrors.aliyun.com/pypi/web/packages/f1/d4/8f2f673e86e1229827a8c77c08ecaf9e547ce65376c007cb235040bbbddf/confluence_poster-1.4.4.tar.gz
BuildArch:	noarch

Requires:	python3-atlassian-python-api
Requires:	python3-typer
Requires:	python3-toml
Requires:	python3-requests
Requires:	python3-pyxdg
Requires:	python3-tomlkit
Requires:	python3-click
Requires:	python3-markdown
Requires:	python3-jinja2
Requires:	python3-typer-cli

%description
# Description

Supplementary script for writing Confluence articles in
local editor. Uses information from the config to post the article content to Confluence.

May be used either on its own:

    $ confluence_poster post-page

Or as a filter:

    $ cat file.md | confluence_poster --file-format markdown post-page

# Getting started

## Installation

1. Install the project from PyPI:

    ```console
    $ pip install confluence-poster
    ```

2. Create the config manually
([sample available in repo](https://github.com/VTimofeenko/confluence_poster/blob/master/config.toml)) or run `confluence_poster create-config` to run a configuration wizard

Alternatively, install `app-text/confluence_poster` from [nitratesky overlay](https://github.com/VTimofeenko/nitratesky).

## Sample usage

User edits the page text and keeps it in file `page1.md`.
Two files `attachment1.docx` and `attachment2.docx` need to be attached to the page.

Given the following files in the current directory:

```
├── attachment1.docx
├── attachment2.png
├── poster_config.toml
└── page1.md
```

`poster_config.toml` contains:

```toml
[pages]
[pages.page1]
page_title = "Some page"
page_file = "page1.md"
page_space = "SPACE"
```

config inside `${HOME}/.config/confluence_poster/` contains the authentication information and the Confluence URL.

Running

```console
$ confluence_poster --config poster_config.toml post-page --upload-files attachment1.docx attachment2.png
```

will attempt to locate the page on Confluence, update its content with the text in `page1.md` and attach the files to it.

If the script cannot locate the page by title, it will prompt the user to create it, optionally under a parent page.

# Details

**Usage**:

```console
$ confluence_poster [OPTIONS] COMMAND [ARGS]...
```

**General Options**:

* `--version`: Show version and exit.
* `--config PATH`: The file containing configuration. If not specified - config.toml from the same directory is used  [default: config.toml]
* `--page-title TEXT`: Override page title from config. Applicable if there is only one page.
* `--parent-page-title TEXT`: Provide a parent title to search for. Applicable if there is only one page.
* `--page-file PATH`: Provide the path to the file containing page text. Allows passing '-' to read from stdin.
* `--password TEXT`: Supply the password in command line.  [env var: CONFLUENCE_PASSWORD]
* `--force`: Force overwrite the pages. Skips all checks for different author of the updated page. To set for individual pages you can specify field 'force_overwrite' in config.
* `--force-create`: Disable prompts to create pages. Script could still prompt for a parent page.
* `--minor-edit`: Do not notify watchers of pages updates. Not enabled by default.
* `--report`: Print report at the end of the run. Not enabled by default.
* `--debug`: Enable debug logging. Not enabled by default.
* `--quiet`: Suppresses certain output.
* `--install-completion`: Install completion for the current shell.
* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
* `--help`: Show this message and exit.

These options can be specified for any `COMMAND` except for  `create-config` which ignores these options.

**Commands**:

* `convert-markdown`: Converts single page text to html.
* `create-config`: Runs configuration wizard.
* `post-page`: Posts the content of the pages.
* `validate`: Validates the provided settings.

# Commands
## `confluence_poster post-page`

Posts the content of the pages.

**Usage**:

```console
$ confluence_poster post-page [OPTIONS] [FILES]...
```

**Options**:

* `--upload-files`: Upload list of files.
* `--version-comment TEXT`: Provider version comment.
* `--create-in-space-root`: Create the page in space root.
* `--file-format [confluencewiki|markdown|html|None]`: File format of the file with the page content. If provided at runtime - can only be applied to a single page. If set to 'None'(default) - script will try to guess it during the run.
* `--help`: Show this message and exit.

## `confluence_poster validate`

Validates the provided settings. If 'online' flag is passed - tries to fetch the space from the config using the
supplied credentials.

**Usage**:

```console
$ confluence_poster validate [OPTIONS]
```

**Options**:

* `--online`: Test the provided authentication settings on the actual instance of Confluence.
* `--help`: Show this message and exit.

## `confluence_poster create-config`

Runs configuration wizard. The wizard guides through setting up values for configuration file.

**Options**:

* `--local-only`: Create config only in the local folder.
* `--home-only`: Create config only in the $XDG_CONFIG_HOME.
* `--help`: Show this message and exit.


# Configuration file format

By default the confluence_poster tries to look for configuration file `config.toml` in the directory where it is invoked and in
$XDG_CONFIG_HOME. The format is as follows:

```toml
# If the page was not updated by the username specified here, throw an error.
# If this setting is omitted - username from auth section is used for checks.
author = "author_username"

[pages]
[pages.default]
# Space key. E.g. for space "local-dev" the space key is "LOC"
# Space defined here will be used if a page section below does not specify it
page_space = "DEFAULT_SPACE_KEY"
[pages.page1]
# The title of the page
page_title = "Some page title"
# The filename with page content
page_file = "some_file.confluencewiki"
# If specified - overrides the default page_space
page_space = "some_space_key"
# If specified as "true" - username check is always skipped for this page
force_overwrite = false
# If specified - the page will be created without looking for a parent under specified parent
page_parent_title = "Parent page title"
# If specified - script will convert the text in the file before posting it. If not specified - script will try to guess it based on file extension.
page_file_format = "confluencewiki"

[pages.page2]
page_title = "Some other page title"
page_file = "some_other_file.confluencewiki"

[auth]
# URL of Confluence instance
confluence_url = "https://confluence.local"
# Username for authentication
username = "confluence_username"
# Password may also be supplied through --password option or from an environment variable CONFLUENCE_PASSWORD
password = "confluence_password"
# Whether the Confluence instance is a "cloud" one
is_cloud = false

```

**Note on password and Cloud instances**: if Confluence instance is hosted by Atlassian, the password is the API token.
Follow instructions at [this link](https://confluence.atlassian.com/cloud/api-tokens-938839638.html).

# File formats

confluence_poster supports the following formats for posting pages:
* [Confluencewiki](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html)
* Markdown
* Html

The format may be specified explicitly in the configuration file, passed during the runtime, or the script will try to guess it by the file extension.

# Contrib directory

There are shell completions for bash and zsh (generated through [typer](typer.tiangolo.com/)) as well as a sample of
[git post-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).

# See also

* [Vim confluencewiki syntax](https://www.vim.org/scripts/script.php?script_id=1994)
* [Paste confluence image in vim](https://github.com/VTimofeenko/confluencewiki-img-paste.vim)
* [Atlassian python API](https://atlassian-python-api.readthedocs.io/en/latest/) (On [Github](https://github.com/atlassian-api/atlassian-python-api))



%package -n python3-confluence-poster
Summary:	Script that updates Confluence articles from files written locally
Provides:	python-confluence-poster
BuildRequires:	python3-devel
BuildRequires:	python3-setuptools
BuildRequires:	python3-pip
%description -n python3-confluence-poster
# Description

Supplementary script for writing Confluence articles in
local editor. Uses information from the config to post the article content to Confluence.

May be used either on its own:

    $ confluence_poster post-page

Or as a filter:

    $ cat file.md | confluence_poster --file-format markdown post-page

# Getting started

## Installation

1. Install the project from PyPI:

    ```console
    $ pip install confluence-poster
    ```

2. Create the config manually
([sample available in repo](https://github.com/VTimofeenko/confluence_poster/blob/master/config.toml)) or run `confluence_poster create-config` to run a configuration wizard

Alternatively, install `app-text/confluence_poster` from [nitratesky overlay](https://github.com/VTimofeenko/nitratesky).

## Sample usage

User edits the page text and keeps it in file `page1.md`.
Two files `attachment1.docx` and `attachment2.docx` need to be attached to the page.

Given the following files in the current directory:

```
├── attachment1.docx
├── attachment2.png
├── poster_config.toml
└── page1.md
```

`poster_config.toml` contains:

```toml
[pages]
[pages.page1]
page_title = "Some page"
page_file = "page1.md"
page_space = "SPACE"
```

config inside `${HOME}/.config/confluence_poster/` contains the authentication information and the Confluence URL.

Running

```console
$ confluence_poster --config poster_config.toml post-page --upload-files attachment1.docx attachment2.png
```

will attempt to locate the page on Confluence, update its content with the text in `page1.md` and attach the files to it.

If the script cannot locate the page by title, it will prompt the user to create it, optionally under a parent page.

# Details

**Usage**:

```console
$ confluence_poster [OPTIONS] COMMAND [ARGS]...
```

**General Options**:

* `--version`: Show version and exit.
* `--config PATH`: The file containing configuration. If not specified - config.toml from the same directory is used  [default: config.toml]
* `--page-title TEXT`: Override page title from config. Applicable if there is only one page.
* `--parent-page-title TEXT`: Provide a parent title to search for. Applicable if there is only one page.
* `--page-file PATH`: Provide the path to the file containing page text. Allows passing '-' to read from stdin.
* `--password TEXT`: Supply the password in command line.  [env var: CONFLUENCE_PASSWORD]
* `--force`: Force overwrite the pages. Skips all checks for different author of the updated page. To set for individual pages you can specify field 'force_overwrite' in config.
* `--force-create`: Disable prompts to create pages. Script could still prompt for a parent page.
* `--minor-edit`: Do not notify watchers of pages updates. Not enabled by default.
* `--report`: Print report at the end of the run. Not enabled by default.
* `--debug`: Enable debug logging. Not enabled by default.
* `--quiet`: Suppresses certain output.
* `--install-completion`: Install completion for the current shell.
* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
* `--help`: Show this message and exit.

These options can be specified for any `COMMAND` except for  `create-config` which ignores these options.

**Commands**:

* `convert-markdown`: Converts single page text to html.
* `create-config`: Runs configuration wizard.
* `post-page`: Posts the content of the pages.
* `validate`: Validates the provided settings.

# Commands
## `confluence_poster post-page`

Posts the content of the pages.

**Usage**:

```console
$ confluence_poster post-page [OPTIONS] [FILES]...
```

**Options**:

* `--upload-files`: Upload list of files.
* `--version-comment TEXT`: Provider version comment.
* `--create-in-space-root`: Create the page in space root.
* `--file-format [confluencewiki|markdown|html|None]`: File format of the file with the page content. If provided at runtime - can only be applied to a single page. If set to 'None'(default) - script will try to guess it during the run.
* `--help`: Show this message and exit.

## `confluence_poster validate`

Validates the provided settings. If 'online' flag is passed - tries to fetch the space from the config using the
supplied credentials.

**Usage**:

```console
$ confluence_poster validate [OPTIONS]
```

**Options**:

* `--online`: Test the provided authentication settings on the actual instance of Confluence.
* `--help`: Show this message and exit.

## `confluence_poster create-config`

Runs configuration wizard. The wizard guides through setting up values for configuration file.

**Options**:

* `--local-only`: Create config only in the local folder.
* `--home-only`: Create config only in the $XDG_CONFIG_HOME.
* `--help`: Show this message and exit.


# Configuration file format

By default the confluence_poster tries to look for configuration file `config.toml` in the directory where it is invoked and in
$XDG_CONFIG_HOME. The format is as follows:

```toml
# If the page was not updated by the username specified here, throw an error.
# If this setting is omitted - username from auth section is used for checks.
author = "author_username"

[pages]
[pages.default]
# Space key. E.g. for space "local-dev" the space key is "LOC"
# Space defined here will be used if a page section below does not specify it
page_space = "DEFAULT_SPACE_KEY"
[pages.page1]
# The title of the page
page_title = "Some page title"
# The filename with page content
page_file = "some_file.confluencewiki"
# If specified - overrides the default page_space
page_space = "some_space_key"
# If specified as "true" - username check is always skipped for this page
force_overwrite = false
# If specified - the page will be created without looking for a parent under specified parent
page_parent_title = "Parent page title"
# If specified - script will convert the text in the file before posting it. If not specified - script will try to guess it based on file extension.
page_file_format = "confluencewiki"

[pages.page2]
page_title = "Some other page title"
page_file = "some_other_file.confluencewiki"

[auth]
# URL of Confluence instance
confluence_url = "https://confluence.local"
# Username for authentication
username = "confluence_username"
# Password may also be supplied through --password option or from an environment variable CONFLUENCE_PASSWORD
password = "confluence_password"
# Whether the Confluence instance is a "cloud" one
is_cloud = false

```

**Note on password and Cloud instances**: if Confluence instance is hosted by Atlassian, the password is the API token.
Follow instructions at [this link](https://confluence.atlassian.com/cloud/api-tokens-938839638.html).

# File formats

confluence_poster supports the following formats for posting pages:
* [Confluencewiki](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html)
* Markdown
* Html

The format may be specified explicitly in the configuration file, passed during the runtime, or the script will try to guess it by the file extension.

# Contrib directory

There are shell completions for bash and zsh (generated through [typer](typer.tiangolo.com/)) as well as a sample of
[git post-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).

# See also

* [Vim confluencewiki syntax](https://www.vim.org/scripts/script.php?script_id=1994)
* [Paste confluence image in vim](https://github.com/VTimofeenko/confluencewiki-img-paste.vim)
* [Atlassian python API](https://atlassian-python-api.readthedocs.io/en/latest/) (On [Github](https://github.com/atlassian-api/atlassian-python-api))



%package help
Summary:	Development documents and examples for confluence-poster
Provides:	python3-confluence-poster-doc
%description help
# Description

Supplementary script for writing Confluence articles in
local editor. Uses information from the config to post the article content to Confluence.

May be used either on its own:

    $ confluence_poster post-page

Or as a filter:

    $ cat file.md | confluence_poster --file-format markdown post-page

# Getting started

## Installation

1. Install the project from PyPI:

    ```console
    $ pip install confluence-poster
    ```

2. Create the config manually
([sample available in repo](https://github.com/VTimofeenko/confluence_poster/blob/master/config.toml)) or run `confluence_poster create-config` to run a configuration wizard

Alternatively, install `app-text/confluence_poster` from [nitratesky overlay](https://github.com/VTimofeenko/nitratesky).

## Sample usage

User edits the page text and keeps it in file `page1.md`.
Two files `attachment1.docx` and `attachment2.docx` need to be attached to the page.

Given the following files in the current directory:

```
├── attachment1.docx
├── attachment2.png
├── poster_config.toml
└── page1.md
```

`poster_config.toml` contains:

```toml
[pages]
[pages.page1]
page_title = "Some page"
page_file = "page1.md"
page_space = "SPACE"
```

config inside `${HOME}/.config/confluence_poster/` contains the authentication information and the Confluence URL.

Running

```console
$ confluence_poster --config poster_config.toml post-page --upload-files attachment1.docx attachment2.png
```

will attempt to locate the page on Confluence, update its content with the text in `page1.md` and attach the files to it.

If the script cannot locate the page by title, it will prompt the user to create it, optionally under a parent page.

# Details

**Usage**:

```console
$ confluence_poster [OPTIONS] COMMAND [ARGS]...
```

**General Options**:

* `--version`: Show version and exit.
* `--config PATH`: The file containing configuration. If not specified - config.toml from the same directory is used  [default: config.toml]
* `--page-title TEXT`: Override page title from config. Applicable if there is only one page.
* `--parent-page-title TEXT`: Provide a parent title to search for. Applicable if there is only one page.
* `--page-file PATH`: Provide the path to the file containing page text. Allows passing '-' to read from stdin.
* `--password TEXT`: Supply the password in command line.  [env var: CONFLUENCE_PASSWORD]
* `--force`: Force overwrite the pages. Skips all checks for different author of the updated page. To set for individual pages you can specify field 'force_overwrite' in config.
* `--force-create`: Disable prompts to create pages. Script could still prompt for a parent page.
* `--minor-edit`: Do not notify watchers of pages updates. Not enabled by default.
* `--report`: Print report at the end of the run. Not enabled by default.
* `--debug`: Enable debug logging. Not enabled by default.
* `--quiet`: Suppresses certain output.
* `--install-completion`: Install completion for the current shell.
* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
* `--help`: Show this message and exit.

These options can be specified for any `COMMAND` except for  `create-config` which ignores these options.

**Commands**:

* `convert-markdown`: Converts single page text to html.
* `create-config`: Runs configuration wizard.
* `post-page`: Posts the content of the pages.
* `validate`: Validates the provided settings.

# Commands
## `confluence_poster post-page`

Posts the content of the pages.

**Usage**:

```console
$ confluence_poster post-page [OPTIONS] [FILES]...
```

**Options**:

* `--upload-files`: Upload list of files.
* `--version-comment TEXT`: Provider version comment.
* `--create-in-space-root`: Create the page in space root.
* `--file-format [confluencewiki|markdown|html|None]`: File format of the file with the page content. If provided at runtime - can only be applied to a single page. If set to 'None'(default) - script will try to guess it during the run.
* `--help`: Show this message and exit.

## `confluence_poster validate`

Validates the provided settings. If 'online' flag is passed - tries to fetch the space from the config using the
supplied credentials.

**Usage**:

```console
$ confluence_poster validate [OPTIONS]
```

**Options**:

* `--online`: Test the provided authentication settings on the actual instance of Confluence.
* `--help`: Show this message and exit.

## `confluence_poster create-config`

Runs configuration wizard. The wizard guides through setting up values for configuration file.

**Options**:

* `--local-only`: Create config only in the local folder.
* `--home-only`: Create config only in the $XDG_CONFIG_HOME.
* `--help`: Show this message and exit.


# Configuration file format

By default the confluence_poster tries to look for configuration file `config.toml` in the directory where it is invoked and in
$XDG_CONFIG_HOME. The format is as follows:

```toml
# If the page was not updated by the username specified here, throw an error.
# If this setting is omitted - username from auth section is used for checks.
author = "author_username"

[pages]
[pages.default]
# Space key. E.g. for space "local-dev" the space key is "LOC"
# Space defined here will be used if a page section below does not specify it
page_space = "DEFAULT_SPACE_KEY"
[pages.page1]
# The title of the page
page_title = "Some page title"
# The filename with page content
page_file = "some_file.confluencewiki"
# If specified - overrides the default page_space
page_space = "some_space_key"
# If specified as "true" - username check is always skipped for this page
force_overwrite = false
# If specified - the page will be created without looking for a parent under specified parent
page_parent_title = "Parent page title"
# If specified - script will convert the text in the file before posting it. If not specified - script will try to guess it based on file extension.
page_file_format = "confluencewiki"

[pages.page2]
page_title = "Some other page title"
page_file = "some_other_file.confluencewiki"

[auth]
# URL of Confluence instance
confluence_url = "https://confluence.local"
# Username for authentication
username = "confluence_username"
# Password may also be supplied through --password option or from an environment variable CONFLUENCE_PASSWORD
password = "confluence_password"
# Whether the Confluence instance is a "cloud" one
is_cloud = false

```

**Note on password and Cloud instances**: if Confluence instance is hosted by Atlassian, the password is the API token.
Follow instructions at [this link](https://confluence.atlassian.com/cloud/api-tokens-938839638.html).

# File formats

confluence_poster supports the following formats for posting pages:
* [Confluencewiki](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html)
* Markdown
* Html

The format may be specified explicitly in the configuration file, passed during the runtime, or the script will try to guess it by the file extension.

# Contrib directory

There are shell completions for bash and zsh (generated through [typer](typer.tiangolo.com/)) as well as a sample of
[git post-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).

# See also

* [Vim confluencewiki syntax](https://www.vim.org/scripts/script.php?script_id=1994)
* [Paste confluence image in vim](https://github.com/VTimofeenko/confluencewiki-img-paste.vim)
* [Atlassian python API](https://atlassian-python-api.readthedocs.io/en/latest/) (On [Github](https://github.com/atlassian-api/atlassian-python-api))



%prep
%autosetup -n confluence_poster-1.4.4

%build
%py3_build

%install
%py3_install
install -d -m755 %{buildroot}/%{_pkgdocdir}
if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
pushd %{buildroot}
if [ -d usr/lib ]; then
	find usr/lib -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/lib64 ]; then
	find usr/lib64 -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/bin ]; then
	find usr/bin -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/sbin ]; then
	find usr/sbin -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
touch doclist.lst
if [ -d usr/share/man ]; then
	find usr/share/man -type f -printf "\"/%h/%f.gz\"\n" >> doclist.lst
fi
popd
mv %{buildroot}/filelist.lst .
mv %{buildroot}/doclist.lst .

%files -n python3-confluence-poster -f filelist.lst
%dir %{python3_sitelib}/*

%files help -f doclist.lst
%{_docdir}/*

%changelog
* Tue Jun 20 2023 Python_Bot <Python_Bot@openeuler.org> - 1.4.4-1
- Package Spec generated