Uploaded image for project: 'Nuxeo Platform'
  1. Nuxeo Platform
  2. NXP-28995

Remove documentation management on explorer

    XMLWordPrintable

    Details

    • Type: Task
    • Status: Resolved
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 11.1, 2021.0
    • Component/s: Explorer
    • Impact type:
      API change, Data Persistence Change
    • Upgrade notes:
      Hide

      The documentation feature is removed: any existing documentation will not be available to the distribution snapshots anymore (persisted or not).

      Added APIs:

      • BundleGroup#getReadmes
      • BundleInfo#getReadme and #getParentReadme

      Changed APIs:

      • OperationInfo#getAliases and #getSignature changed to used lists instead of arrays for consistency
      • same for OperationWO#getInputs and OperationWO#getOutputs

      Removed APIs:

      • NuxeoArtifact#getAssociatedDocuments
      • ArtifactSearcher#searchDocumentation
      • NuxeoArtifactWebObject#getAssociatedDocuments
      • NuxeoArtifactWebObject#doCreateDocumentation
      • NuxeoArtifactWebObject#doUpdateDocumentation
      • NuxeoArtifactWebObject#doDeleteDocumentation
      • NuxeoArtifactWebObject#doAddDoc
      • NuxeoArtifactWebObject#doEditDoc
      • NuxeoArtifactWebObject#quickEdit
      • NuxeoArtifactWebObject#quickEditSave
      • BundleInfo#getLiveDoc and #getParentDoc
      • Distribution#getDocumentationInfo
      • Distribution#downloadDoc (linked to "downloadDoc" rest api)
      • Distribution#uploadDoc (linked to "uploadDoc" rest api)

      Removed Classes:

      • DocumentationService
      • DefaultDocumentationType
      • interface AssociatedDocuments and implementation AssociatedDocumentsImpl
      • interface DocumentationItem and AbstractDocumentationItem, and implementations SimpleDocumentationItem and ResourceDocumentationItem (migrated to Bundle and BundleGroup API)
      • DocumentationItemDocAdapter
      • DocumentationItemReader
      • DocumentationWO
      • ApiBrowser#getDescriptions
      Show
      The documentation feature is removed: any existing documentation will not be available to the distribution snapshots anymore (persisted or not). Added APIs: BundleGroup#getReadmes BundleInfo#getReadme and #getParentReadme Changed APIs: OperationInfo#getAliases and #getSignature changed to used lists instead of arrays for consistency same for OperationWO#getInputs and OperationWO#getOutputs Removed APIs: NuxeoArtifact#getAssociatedDocuments ArtifactSearcher#searchDocumentation NuxeoArtifactWebObject#getAssociatedDocuments NuxeoArtifactWebObject#doCreateDocumentation NuxeoArtifactWebObject#doUpdateDocumentation NuxeoArtifactWebObject#doDeleteDocumentation NuxeoArtifactWebObject#doAddDoc NuxeoArtifactWebObject#doEditDoc NuxeoArtifactWebObject#quickEdit NuxeoArtifactWebObject#quickEditSave BundleInfo#getLiveDoc and #getParentDoc Distribution#getDocumentationInfo Distribution#downloadDoc (linked to "downloadDoc" rest api) Distribution#uploadDoc (linked to "uploadDoc" rest api) Removed Classes: DocumentationService DefaultDocumentationType interface AssociatedDocuments and implementation AssociatedDocumentsImpl interface DocumentationItem and AbstractDocumentationItem, and implementations SimpleDocumentationItem and ResourceDocumentationItem (migrated to Bundle and BundleGroup API) DocumentationItemDocAdapter DocumentationItemReader DocumentationWO ApiBrowser#getDescriptions
    • Team:
      AT
    • Sprint:
      nxAT 11.1.16, nxAT 11.1.17
    • Story Points:
      3

      Description

      The current documentation mechanism is a problem because:

      • it implies persistence, that could be an issue when isolating the code logics to introspect a live instance without exposing explorer specific contributions, see NXP-28962
      • the feature is not much used (and has been broken for a while actually, see NXP-20246, NXP-23830)
      • content is difficult to review, see NXDOC-2111, and as far as i can see, is not currently visible anywhere on operations (the most documented ones).

      Potential options:

      • completely remove this feature, and maybe update contributions extracted to reference these external links directly in the introspected code (like it's already done on some operations)
      • add a dedicated field in persisted distributions only, that would allow referencing documentation from doc.nuxeo.com by providing simple content (titles and links only?) and only reference these links, or embed them in frames
        • drowback: these would need to be updated on each persisted distribution, at each release

      Note the bundle and bundle group README from the GiHub repository was handled as a "documentation" item, so the corresponding documentation will be embedded directly on the bundle and bundle group instead.
      As per nuxeo root pom configurations, maven will assemble this doc in the jar in subdirectories "doc" and "doc-parent". Patterns taken into account:

      <include>*.md</include>
      <include>readme*</include>
      <include>ReadMe*</include>
      <include>README*</include>
      

      BUT the main maven groups (at least in the nuxeo repository) are currently not that accurate, and parent documentation association with bundle group is currently buggy --> see how/if that information to be highlighted on the explorer.

        Attachments

          Issue Links

            Activity

              People

              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Time Tracking

                  Estimated:
                  Original Estimate - Not Specified
                  Not Specified
                  Remaining:
                  Remaining Estimate - 0 minutes
                  0m
                  Logged:
                  Time Spent - 4 days, 2 hours, 15 minutes
                  4d 2h 15m

                    PagerDuty

                    Error rendering 'com.pagerduty.jira-server-plugin:PagerDuty'. Please contact your Jira administrators.