confluencebuilder

confluencebuilder copied to clipboard

For some external restrictions I am not allowed to publish from where I am allowed to build the docs, and I am not allowed to build the docs where I am allowed to publish them.

So I was wondering if there is a recommended way to publish to confluence the docs if I have to build with confluence_publish = False.

Thanks!

Unfortunately, there is no way to perform publishing of a documentation set without the build being performed within the same runtime. At this time, a publishing event relies on a combination of the documentation's configuration (such as label information, dry-run modes, purging mode, etc.); but more so on a chunk of state information cached (in memory) during the build process (e.g. document order (for hierarchy/nested pages), a document's title name, etc.).

We could try to find a way to persist this cache information to allow a user to invoke these two stages with two invokes -- I assume for an environment where a container may build and then forward it to a container which can publish (I'd be curious to know the use case to help better plan for such a requirement)? Although, I am not sure the complexities this may introduce off hand.

---

Although, if this question is more about trying to override a project which may have confluence_publish explicitly set in the configuration, note that command line options provided can override these options. For example, if a project (conf.py) defines:

confluence_publish = False

A build such as follows will (explicitly) not publish with an invoke as follows:

sphinx-build -b confluence . _build/confluence -E -a

However, if you override the publish argument as follows, a publish event should trigger:

sphinx-build -b confluence . _build/confluence -E -a -D confluence_publish=1

Thanks @jdknight !

The use case is really similar to what you have described:

I assume for an environment where a container may build and then forward it to a container which can publish

Since we have the option to set confluence_publish to False I thought that maybe there was a standard way to make use of the generated docs. I will keep looking for ways to run both stages in a single container for now.

This might not be a very common use case, but If you consider worth adding this feature I will be glad to contribute.

Should I close this issue?

We can leave this issue open, if desired, to track this enhancement request. Although, if you wanted to close it, that is fine as well (I can keep the idea in the back of my mind as I try to... someday... complete the initial work for new ADF/editor types).

Note though, at this time, I do not have an optimistic feeling on this. While I do not mind trying to find a way forward to support staged environments like this, there is a lot of complexity involved here. Without getting into how/what content to cache (to a file?) between the building and publishing steps, it seems like a "proper" end goal here is to completely separate the publishing aspect from the Sphinx extension. While the idea of this is fine, it is kind of moving outside the scope of what this extension was designed for. We could have this extension generate a "publishable Confluence content set", which includes the Confluence documents as well as all other required configuration mappings (space information, page order, dealing with multi-pass publishing for future ADF support, etc.) -- but I would imagine something like this would be better served with two libraries (i.e. this extension for Sphinx; and another with a structured export that can be published). I am just not sure if it's worth the effort.

That being said, if the focus was more for reducing complete rebuild times between a "building" pipeline and a "publishing" pipeline, enhancements for that could properly be good (e.g. avoiding the need to re-process SVGs, rebuilding PNGs for some extensions, etc.) -- but I wouldn't say such changes are trivial as well (considering it involves more than just this extension).

Since we have the option to set confluence_publish to False I thought that maybe there was a standard way to make use of the generated docs.

Yeah -- that option can be extremely misleading. In reality, this extension is more of a "suite" of features to deal with taking reStructuredText/Markdown and bringing it to a Confluence instance. Disabling publishing is typically for users who temporarily want to test builds/etc., without having to worry about pushing content to an actual instance.

The original purpose/target goal (at least for myself, as a maintainer) is to just provide a way to promote the use of reStructuredText/Markdown for documentation, where if a user is in an environment where they need to publish to Confluence, this extension can help support this.

Long term, there can be better ways this extension can evolve with other libraries. For example (in theory):

Content -> Sphinx -> (this extension) -> Confluence-Export-Package -> Some Confluence Importing tool (which may use "atlassian-python-api"'s Confluence module) -> Confluence Instance

(kind of reiterating what I previously said above)

But again, outside of my own desired scope at this time.

Considering this more over the recent months, will go ahead and close this issue. As discussed in the length comment above, this capability is not planned to be done by the active maintainer group. If a user wished to submit a series of changes to help support this, the changes would be welcome (and can be discussed more in the presented pull request). Sorry for those users who may need this capability -- the only recommendation at this time is to ensure the publishing container is a superset of the building container, so that the project can be rebuild/published (less than ideal).