[solved] confluencebuilder can only push drafts?

[sarnold]

Sorry, I hate to be that guy but my confluence docs build suddenly started creating blank drafts in my confluence doc "space" and I have no idea what change could cause that to happen. (also you should know that I only occasionally need to use confluence and I absolutely hate using anything related to atlassian/confluence/jira/bitbucket; the passkey mostly works but that's about it)

I do use a ton of sphinx on all my python projects so I am not unfamiliar with the tools, rather it's the upstream Atlassian nastiness that makes me sad :(

In order to use this thing I made a stand-alone docs build repo to contain doc sources, a tox file, and the confluence API key so building the docs and publishing the result is fairly clean, and of course it worked fine a few weeks ago. Sadly now all of my new content (ie, a handful of short .rst files) shows only the doc titles in confluence and when I click on a title I get a blank file in the editor and a PUBLISH button (unused so far because why would I want to publish an empty page).

Lastly it's even more sad that all of this is private/not available in public repos so I can only paste a few things here.

If you have any ideas I'll happily try them, so far I haven't found anything helpful searching the Intarweb.

build/publish with DRY_RUN true:

$ DEBUG=true tox -e docs
docs: commands_pre[0]> doorstop publish REQ docs/source/ds/reqs_tree.md
building tree...
publishing document REQ to '/home/user/my_stuff/work/work/TDS/confluence_pub/docs/source/ds/reqs_tree.md'...
published: /home/user/my_stuff/work/work/TDS/confluence_pub/docs/source/ds/reqs_tree.md
docs: commands_pre[1]> doorstop publish SDD docs/source/ds/sys_design.md
building tree...
publishing document SDD to '/home/user/my_stuff/work/work/TDS/confluence_pub/docs/source/ds/sys_design.md'...
published: /home/user/my_stuff/work/work/TDS/confluence_pub/docs/source/ds/sys_design.md
docs: commands_pre[2]> bash docs/sphinx_prep.sh docs/source/ds/reqs_tree.md
Processing markdown file: docs/source/ds/reqs_tree.md
Success
docs: commands_pre[3]> bash docs/sphinx_prep.sh docs/source/ds/sys_design.md
Processing markdown file: docs/source/ds/sys_design.md
Success
docs: commands[0]> make -C docs confluence
make: Entering directory '/home/user/my_stuff/work/work/TDS/confluence_pub/docs'
Running Sphinx v9.1.0
Using API file: /home/user/my_stuff/work/work/TDS/confluence_pub/confluence.api
Publish settings: {'API_PATH': 'confluence.api', 'DRY_RUN': 'true', 'API_USER': 'user@example.com', 'SPACE_KEY': 'DEVOPS', 'DEBUG': 'true'}
loading translations [en]... done
making output directory... done
myst v5.1.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'attrs_block', 'tasklist', 'amsmath', 'substitution', 'colon_fence', 'fieldlist', 'deflist', 'dollarmath'}, disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive={'mermaid'}, number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, strikethrough_single_tilde=False, colon_fence_exact_match=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output... 
building [confluence]: targets for 9 source files that are out of date
updating environment: [new config] 9 added, 0 changed, 0 removed
reading sources... [100%] ubuntu-deploy
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents...  done
pre-process assets... [100%] autoinstall-cloud-init-workflow
pre-process assets: done
copying assets... 
copying assets: done
writing output... [100%] ubuntu-deploy
building manifest... done
build succeeded.
make: Leaving directory '/home/user/my_stuff/work/work/TDS/confluence_pub/docs'
  docs: OK (1.05=setup[0.03]+cmd[0.23,0.20,0.01,0.00,0.57] seconds)
  congratulations :) (1.07 seconds)

same thing with DRY_RUN false:

$ DRY_RUN=false DEBUG=true tox -e docs
docs: commands_pre[0]> doorstop publish REQ docs/source/ds/reqs_tree.md
building tree...
publishing document REQ to '/home/user/my_stuff/work/work/TDS/confluence_pub/docs/source/ds/reqs_tree.md'...
published: /home/user/my_stuff/work/work/TDS/confluence_pub/docs/source/ds/reqs_tree.md
docs: commands_pre[1]> doorstop publish SDD docs/source/ds/sys_design.md
building tree...
publishing document SDD to '/home/user/my_stuff/work/work/TDS/confluence_pub/docs/source/ds/sys_design.md'...
published: /home/user/my_stuff/work/work/TDS/confluence_pub/docs/source/ds/sys_design.md
docs: commands_pre[2]> bash docs/sphinx_prep.sh docs/source/ds/reqs_tree.md
Processing markdown file: docs/source/ds/reqs_tree.md
Success
docs: commands_pre[3]> bash docs/sphinx_prep.sh docs/source/ds/sys_design.md
Processing markdown file: docs/source/ds/sys_design.md
Success
docs: commands[0]> make -C docs confluence
make: Entering directory '/home/user/my_stuff/work/work/TDS/confluence_pub/docs'
Running Sphinx v9.1.0
Using API file: /home/user/my_stuff/work/work/TDS/confluence_pub/confluence.api
Publish settings: {'API_PATH': 'confluence.api', 'DRY_RUN': 'false', 'API_USER': 'user@example.com', 'SPACE_KEY': 'DEVOPS', 'DEBUG': 'true'}
loading translations [en]... done
loading pickled environment... The configuration has changed (31 options: 'confluence_add_secnumbers', 'confluence_adv_ignore_nodes', 'confluence_adv_restricted', 'confluence_cloud', 'confluence_disable_notifications', ...)
done
myst v5.1.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'attrs_block', 'deflist', 'dollarmath', 'fieldlist', 'tasklist', 'colon_fence', 'substitution', 'amsmath'}, disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive={'mermaid'}, number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, strikethrough_single_tilde=False, colon_fence_exact_match=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output... 
building [confluence]: targets for 0 source files that are out of date
updating environment: 0 added, 2 changed, 0 removed
reading sources... [100%] ds/sys_design
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents...  done
pre-process assets... [100%] autoinstall-cloud-init-workflow
pre-process assets: done
copying assets... 
copying assets: done
writing output... [100%] index
publishing documents... [100%] ds/sys_design
building intersphinx... done
publishing assets... [100%] objects.inv
Publish point: https://corp.atlassian.net/wiki/spaces/DEVOPS/pages/66424340483
building manifest... done
build succeeded.
make: Leaving directory '/home/user/my_stuff/work/work/TDS/confluence_pub/docs'
  docs: OK (5.66=setup[0.04]+cmd[0.21,0.19,0.00,0.00,5.21] seconds)
  congratulations :) (5.68 seconds)

[sarnold]

After poking around more in the closed issues I found these config options which did clean out enough cruft that my new doc bits actually showed up as published. Not sure if I'm supposed to leave them in but for now it seems like a good idea to keep them.

[jdknight]

@sarnold, glad to hear you got it working. Utilizing confluence_cleanup_purge permanently is fine for a setup, especially if page titles are expected to be renamed over time. The option is only disabled by default to avoid risks of new users misconfiguring initial setups and resulting in entire spaces to being cleared. I cannot explicitly explain why pages that (I assume) should have content would be blank. If it is believed to be a result of stale content that is now cleaned up, great. However, if it keeps happening in the future, this is unexpected.

Sphinx has a lot of capabilities and this extension tries to do what it can with the capabilities Confluence provides. I feel the biggest quirk to know when switching/complementing publications on Confluence is knowing limitations about "Confluence spaces and unique page names".

If planning with a lot of Sphinx projects and trying/testing publications across one (or more spaces), note that this extension will only publish pages if content is changed. We track hashes of pages/attachments via properties/comment-fields and check to help avoid extra publishing time. If you ever get in a state where something you feel is not updated, you may be interested in the confluence_publish_force option to help "force" a publish. Although, it is only recommend using that option in special cases -- but worst case, it is just more API calls and time to publish.

[sarnold]

I think there might be (probably is) something wrong with my workflow or conf.py since i just got another error traceback after adding those ^^ config options. The options did work fine at first, including today when I added a new doc source (and forgetting to update index.rst). But when I added the new source file to the index and rebuilt the docs I got a not-so-nice error traceback with several things I don't understand:

• what exactly is "trample" and why is it an error?
• can you explain what the page conflict is?
• i didn't change any doc names, only added a new one
• should i enable the suggested "confluence_publish_trample" option?
• is there a downside to that?
• is there some other config option I should use?

The workflow itself is just tox creating a virtual env and running the build command, but I also have a clean cmd - should I stop using that?

sphinxcontrib.confluencebuilder error!

Versions
========

* Platform:         linux; (Linux-7.0.13-gentoo-dist-bin-x86_64-AMD_Ryzen_7_7840U_w-_Radeon_780M_Graphics-with-glibc2.43)
* Python version:   3.14.6 (CPython)
* Sphinx version:   9.1.0
* Docutils version: 0.22.4
* Jinja2 version:   3.1.6
* Pygments version: 2.20.0

Last Messages
=============

    jenkins-deploy


    publishing documents... [ 70%]
    ubuntu-deploy


    publishing documents... [ 80%]
    artifact-deploy

Loaded Extensions
=================

* sphinx.ext.mathjax (9.1.0)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* sphinxcontrib.confluencebuilder (3.1.0)
* myst_parser (5.1.0)
* sphinxcontrib.mermaid (9.1.0)

Traceback
=========

      File "/home/user/my_stuff/work/corp/TDS/confluence_pub/.tox/docs/lib/python3.14/site-packages/sphinxcontrib/confluencebuilder/publisher.py", line 1613, in _check_allowed_page_update
        raise ConfluencePublishTrampleError(page_name, webui)
    sphinxcontrib.confluencebuilder.exceptions.ConfluencePublishTrampleError: 
    ---
    Documentation trample detected: Artifact deployment
    
    A request has been made to publish a page which updates an existing page not
    contained in the expected hierarchy. This typically is a result of a conflict
    between an existing Confluence space's documentation and the documentation
    attempted to being published (i.e. a page name conflict).
    
    The conflicting page can be found at:
    
        https://truedigitalsurgery.atlassian.net/wiki/spaces/DEVOPS/pages/66599092227/Artifact+deployment
    
    If the page move is desired, users can either:
    
     - Move the existing page manually under the hierarchy of the root document.
     - Remove the conflicting page.
     - Enable the `confluence_publish_trample` option.
    
    For more information, please see:
    
        https://sphinxcontrib-confluencebuilder.readthedocs.io/tips/#confluence-spaces-and-unique-page-names
    ---


The full traceback has been saved in:
/tmp/sphinx-err-tcq430is.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
make: Leaving directory '/home/user/my_stuff/work/corp/TDS/confluence_pub/docs'
make: *** [Makefile:20: confluence] Error 2
docs: exit 2 (17.21 seconds) /home/user/my_stuff/work/corp/TDS/confluence_pub> make -C docs confluence pid=2462327
  docs: FAIL code 2 (17.67=setup[0.04]+cmd[0.22,0.20,0.00,0.01,17.21] seconds)
  evaluation failed :( (17.69 seconds)

[sarnold]

Oh, and confluence_publish_force did nothing for that ^^ error BUT the trample option allowed the build to succeed.

[jdknight]

what exactly is "trample" and why is it an error?

The exception you provided does give an indication of what is happening. If the messaging is not great, maybe we should update it to add a line such as:

"... to being published (i.e. a page name conflict). This publish event has been stopped to avoid trampling/overwriting the conflicting page. The conflicting page can be found at: ..."

can you explain what the page conflict is?

Publishing is mad about a page named Artifact deployment. Did you have an existing page already with the name Artifact deployment? Or by chance, does your documentation have more than one page with the name Artifact deployment?

should i enable the suggested "confluence_publish_trample" option?

Only if you do not care to overwrite existing pages outside the working hierarchy of your documentation found on the space you are publishing to.

is there a downside to that?

The downside only exists in scenarios where users have a combination of pages that are managed in Confluence and a subset of pages expected to be automatically published via this extension.

is there some other config option I should use?

It would be interesting to know if you keep getting the trample warning constantly as you publish new results. Maybe there is more of a specific error case happening that is being masked by the hierarchy detection.

I also have a clean cmd - should I stop using that?

If this is in reference to confluence_cleanup_purge, it is perfectly find to leave it in. The cleaning performs post-cleanup work of stale pages/attachments and would not cause issues related to publishing new/updated documents.

confluence_publish_force did nothing for [the trample issue]

This is expected. The force option is more about forcing publication even when hash checks detect no page data changes. The option does not break the trample guard.

[sarnold]

Thanks. Some of that makes sense except the trample scenario. Also we don't really edit through the web, and I don't see a way to "pull" changes to docs via the web, so "fixit" edits would need to be migrated to the source files.

As for the above error, I was trying to say the error happened on the build immediately after the (new) Artifact deployment doc was added. The only change was adding the "Artifact deploy" title to the index.rst file.

[sarnold]

Also I really do appreciate this extension otherwise I'm not sure if I would touch confluence at all (it's really a customer thing in the first place). Thanks!

Oh yeah, my normal dev docs workflow looks more like these templates: https://github.com/orgs/VCTLabs/repositories?q=template

[jdknight]

I don't see a way to "pull" changes to docs via the web

To clarify, there is no support related to pulling documents from the web back into a source repository with this extension.

My comments about overwrites/trampling/etc. are about having a given Confluence space using a mix of documentation. A subset of pages based on what people may add in Confluence itself using "normal" interaction; and having a subset of pages that are generating from publishing. Not all users may have the flexibility in their environment to have or easily create spaces, so they may attempt to mix manual Wiki content and generated documentation (even publish different documentation sets on a given space). This tool tries to provide some limited guards/protections to help prevent conflicts and overwriting pages -- as Confluence has the "limitation" of unique page names.