[notice/rfc] changes to defaults hierarchy mode and max-doc-depth features

[jdknight]

Changes made in this extension attempt to minimize any impact from updates on existing setups. A lot has changed over the years and there are two adjustments planned to better serve "most" users which could affect a subset of users with existing configurations. This notice aims to inform and provide a window for any concerned user to comment about the changes proposed.

summary

• confluence_page_hierarchy will be default changed to True
• confluence_max_doc_depth will be removed
• Changes will take effect next major release

[change 1] Defaulting hierarchy mode to enabled

In the early changes of confluencebuilder, this extension had no concept of page hierarchy. Documents were dumped to the root or configured base point, where users could manually sort them using Confluence's page ordering UI. Over time, the confluence_page_hierarchy option was added to publish pages in a hierarchically order (based off the configured main document and document's toctree definitions).

In most cases, users will be using this configuration when multiple documents are being used. The proposed change is to adjust hierarchy mode to be enabled by default.

confluence_page_hierarchy = True

This change will give new users the best experience in dealing with large documentation sets by taking advantage of Confluence's navigation tree. However, this change will cause existing setups which do not explicitly configure confluence_page_hierarchy to be switch from a "flat mode" into a hierarchy mode.

To handling this future change, it is recommended that users who use a "flat mode" to explicitly disable hierarchy mode in their configurations:

confluence_page_hierarchy = False

[change 2] Removing max-doc-depth feature

A helpful change in the early days of this extension was the confluence_max_doc_depth feature. This aided users who wish to focus on publishing a documentation set into a small area -- primarily, to a single document. In more recent changes, this extension has evolved to include multiple builders, where now this extension provides a confluence builder and a singleconfluence builder (akin to html and singlehtml). Since there is now a builder dedicated to squashing documents into a single page, the proposal here is to remove the confluence_max_doc_depth from this extension.

Aside from the assumption that singleconfluence fulfills all users desires who used the max-doc-depth (please, reply if this is not the case), this change is primarily being driven due to prospect maintenance improvements in this extension. The max-doc-depth feature in this extension does some big manipulations in order to properly squash documents. This includes overriding the Sphinx application's get_doctree call to cache doctree entries as well as manually replicating/invoking implementation to correct domain label issues from overriding the get_doctree call. This increases maintenance risks as the Sphinx engine evolves, increases this extension's implementation size and can cause issues when interacting with other extensions.

For new users, this will most likely not affect them. Ideally any new users who may have started to use this extension took advantage of the singleconfluence builder (if there was a desire for them to squash documents). For users with older configurations where the confluence_max_doc_depth is configured to zero, the recommended workaround is to drop the configuration and start using singleconfluence today. For example:

python -m sphinx -b singleconfluence . _build/singleconfluence -E -a

For users who do use the confluence_max_doc_depth feature with a non-zero value, please leave a comment describing your use case. There is a desire to help give users a good experience to help promote Sphinx when in Confluence-dependent environments -- at this time, this change can better user most (if not all users) long term.

When these changes will happen

The proposed changes, if accepted, will take place in a v2.0 release. At the time of writing, v1.5 is the current release. There will be at least one future minor release (e.g. v1.6). In a future minor release, deprecation warnings will be added to help warn users before a following release. In theory, the next release will then be a v2.0 release with the proposed changes completed.

[jdknight]

Changes mentioned above have been applied to the main development branch, and will be available next release.

[jdknight]

v2.0 is now available on PyPI -- marking as closed.