The import tool could be extended to provide a way to easily consume external documentation for use within content specs. I imagine the process would work something like this: 1. An initial import of the upstream documentation would be done to create a content spec. 2. The topics in this content spec can be used in other documentation. They would have to be referenced at a specific revision to ensure that subsequent imports would not change the content in the second content spec. 3. The upstream documentation would be reimported over the content spec created in step 1. This could either be a manual process or an automated sync. 4. A report that showed what had been updated would be helpful for those looking to incorporate the changes into their own documentation.
OpenStack relies heavily on upstream docs, and RH OStack team contribute upstream. Several of the docs on the OpenStack docs page are being or will be used as the basis for RH docs: http://docs.openstack.org/ For example: End User Guide Admin User Guide Command-Line Interface Reference Configuration Reference Cloud Administrator Guide High Availability Guide Being able to reliably import into PGang (and track changes when one syncs downstream with upstream) would be very useful.
Rudi has been looking at this problem from the OpenStack viewpoint. The problem is not the initial import, but rather that step 3 would be a bear. Not only do topics and structures change upstream, but both topics and structures then have to be RH-scrubbed as well.
Created attachment 909381 [details] Example of an original book that might be imported
Created attachment 909382 [details] Example of a book that has some edits
Created attachment 909771 [details] Highlights of edits between original and edited book
Initial work deployed with Build 1.7-SNAPSHOT 201406180638 The process works like this. 1. Import some content, creating a new content spec, new topics, new images and new files. This is a clean import. The OriginalBook.zip attachment can be used as a test. Make a note of the spec id. 2. Reimport the content after it has been updated. Overwrite the spec created in step 1, and reuse topics, images and files. The EditedBook.zip attachment can be used as a test. When overwriting a spec and reusing topics, the import tool will reuse topics that are an exact match between the original import and the new import, or overwrite existing topics referenced by the spec where those topics are substantially similar to the content being imported. This means that edits are saved to PressGang as new revisions to existing topics. Where the imported content can not be matched to topics referenced by the spec, new topics are created. The final report screen and comments at the bottom of the imported spec list 3 groups of topics: * Newly Created Topics - These are topics that were created as part of the import, and represent content that could not be matched to the original spec. * Updated Topics - These are topics that were updated in the imported content, and we matched to topics already present in the original spec. Viewing the revision history for these topics will show what was changed between the initial and subsequent imports. * Reused Topics - These are topics that matched the imported content exactly. When reimporting upstream content, the list of new and updated topics can be used to find out what changed between the original import and the new import.
Fixed in Build 1.7-SNAPSHOT 201406181226 Currently reused files and images can come from any that match, and not just those that might be referenced by the content spec being overwritten. See BZ#1110565 for that feature.
Created attachment 910140 [details] Sample asciidoc book
Created attachment 910141 [details] Sample asciidoc book with edits
Created attachment 910144 [details] Sample ODT book
Putting this back on assigned as the ODT import has some issues.
Created attachment 910162 [details] Sample ODT book with edits
Build 1.7-SNAPSHOT 201406190923 fixes the ODT import.
Verified importing via a clean import (ie no re-use), then doing updates on original source and re-importing overwrote minor changes, imported new topics and removed topics that are no longer used. One thing to note with the overwrite part is that it may affect topics that have been shared after the initial import, or re-used existing topics in the initial import. However in this case if the user who used the topic from the initial import didn't freeze it then that means that they should want all future updates. As such I don't see this as an issue, but it is something to keep in mind (for docs or other purposes).
This follows on from the note above, but container target ID's change during an overwrite which could lead to shared topics becoming invalid for some specs (see BZ#1110981 for more details).
Verified that both asciidoc and odt imports work as expected.
Verified that Mojo docs are imported as expected. Updated topics don't have the revision message set.
Verified that the reports show the three different topic types as expected. One additional report that might be handy is removed topics, however this can be retrieved from the rev history diff view if really needed.
Fixed in Build 1.7-SNAPSHOT 201406200631 Discarded topics are now listed in the final report and as a comment in the spec when a spec is overwritten. Only topics that are referenced only by the spec being overwritten will be updated. This prevents shared topics from being updated with potentially invalid changes.
> Only topics that are referenced only by the spec being overwritten will be updated. This prevents shared topics from being updated with potentially invalid changes. That was worded badly. What I meant to say was that the only topics that will be overwritten are those that are referenced by the spec that is being overwritten and by no other spec.
Created attachment 910590 [details] Sample of overwrite import Tried the same steps I did for Comment #15 (so a clean import followed by an overwrite) and no topics were re-used. Additionally the stats do not reflect the content in the report.
Additionally it looks like Updated Topics still don't have a log message which was the original reason I failed this RFE (see Comment #20). In saying that though I can't test this atm due to the problem above, so this is based solely on the commits.
Fixed in Build 1.7-SNAPSHOT 201406200915 I had a "=== 0" instead of a "=== 1" >:(
Hehe easily enough to do, anyways looks all good now, so verified!