confluencebuilder

confluencebuilder copied to clipboard

Confluence does not allow this, which is noted in this repos documentation. This project allows prefixes and suffixes to help alleviate a bit of the pain when trying to push generated pages into spaces that have manually generated pages with the postfix and prefix configs.

The issue arrises is what if I want multiple pages with the same title throughout my source directory that I am trying to push to confluence. ie readme pages for different directories, how-tos, results for analyses etc. People suggest using manual suffixes for each page that has the same title but that is too much of pain for us. So the question is how to do this within this project but still make the suffixes / prefixes consistent even different people run sphinx and push to confluence. You wouldn't want it to keep purging pages and creating new pages and thus destroying links if different people run it.

My answer was create a hash to the path to the source file and append it to the end of the title when registering the title for a page. So if readme is in different subfolders it will be a different hash and its title will be something like readme -xk3432zt and readme -zpo778d34 . I also have a path relative part of this since different user's are going to have a different absolute path.

I am currently finishing my testing of this feature but wanted to know if others had a better solution and/or if this is something that other's might want in the main fork.

If in a situation where multiple projects are processed and published to a single Confluence space (either through a "main" Sphinx project with sub-projects; or multiple independent Sphinx projects), I can agree that it can be less than ideal in trying to prevent/manage conflicts. If individual projects do not wish to manage their own prefix/postfix entries, conflicts are bound to arise for common document titles (as already mentioned).

Aside from having projects managing prefix/postfix overrides for a project (even for versions of a project), the only other pattern I have seen is projects naming their documents with unique/nesting patterns. For example, the leading titles named something such as:

 libfoo/About
 libfoo/Releases/1/ChangeSet
 libfoo/Releases/2/ChangeSet
 libfoo/Releases/3/ChangeSet
 libfoo/SomeCapability

But this is most likely not ideal for most projects, especially when mixing both Confluence publications with another format.

Your prospect work into generating a hash for a document to postfix is not a bad idea. It is a similar pattern used in environments where account identifiers are postfixed with trailing hash/code. The only gain I see off hand is that instead of each project assigning a custom postfix value in their configuration, they would instead apply a flag (or, in your prospect case, a base-path) in their configuration without needing to care about what the postfix value is. There would be no guarantee that conflicts will not occur, but depending on the hash length, maybe it could be rare.

A suggestion, if I may. I would think it may be best to introduce a title transform option first. For example, something like confluence_title_transform, which accepts a function call that can allow a project's configuration a way to override how a final title value is populated. Such an option would provide flexibility for any project wishing to customize their title creation without major influence from this extension (and not have to deal with managing title override mappings or dealing with the prefix/postfix options). This will also allow projects to customize their title entries if they wish to do minor tweaks to generated hashes in titles. For example, while your proposal introduced a dash-leading postfixed alphanumeric value, another user may wish to have a parenthesis enclosed numerical value instead.

One thing I do not completely understand from the prospect work is the definition of the confluence_title_hash_root_path option. I am not sure off hand why a path value needs to be provided here. I would assume that a project could use the project value has a unique value to drive the hash generation for documents. Assuming that confluence_title_transform is added (as mentioned above), there could be a chance to add a special case where a user could define confluence_title_transform = 'auto', which automatically generated hash values for generated pages (in a pattern like you have proposed). That being said, if I am overlooking a key piece to why including a base path in a confluence_title_hash_root_path option brings, please let me know.

@finkedave, thanks for the changes to support this (with all the changes along the way). Hopefully it serves your use case well, and possibly help others in the similar situations.

This feature should be available next stable release on PyPI (v1.9+).

v1.9 is now available on PyPI -- marking as closed.

@finkedave, thanks for the changes to support this (with all the changes along the way). Hopefully it serves your use case well, and possibly help others in the similar situations.

This feature should be available next stable release on PyPI (v1.9+).

@jdknight Thanks so much for being so open and helping us get this feature in here, This repos saved us so much time and effort. huge fan. Hoping I can contribute more in the future