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
    • Epic Link:
    • 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

          depends on

          Improvement - An improvement or enhancement to an existing feature or task. NXP-28915 Compute bundle and component requirements in Explorer

          • Major - Major loss of function.
          • Resolved

          Improvement - An improvement or enhancement to an existing feature or task. NXP-29219 Rework Explorer security model

          • Major - Major loss of function.
          • Resolved

          Improvement - An improvement or enhancement to an existing feature or task. NXP-28913 Improve Explorer webengine navigation and display

          • Minor - Minor loss of function, or other problem where easy workaround is present.
          • Resolved
          is related to

          Bug - A problem which impairs or prevents the functions of the product. NXP-29103 Fix explorer bundle group introspection and json

          • Minor - Minor loss of function, or other problem where easy workaround is present.
          • Resolved

          Bug - A problem which impairs or prevents the functions of the product. NXDOC-2111 Update links in explorer.nuxeo.com

          • Minor - Minor loss of function, or other problem where easy workaround is present.
          • Open

          Bug - A problem which impairs or prevents the functions of the product. NXP-23830 "Manage documentation" links give a 500 error

          • Major - Major loss of function.
          • Resolved

          Bug - A problem which impairs or prevents the functions of the product. NXP-20246 Make some explorer pages more robust

          • Minor - Minor loss of function, or other problem where easy workaround is present.
          • Resolved

          New Feature - A new feature of the product, which has yet to be developed. NXP-28962 Split the explorer introspection and persistence features

          • Major - Major loss of function.
          • Open

          Improvement - An improvement or enhancement to an existing feature or task. NXP-29046 Fix some Nuxeo maven groups

          • Minor - Minor loss of function, or other problem where easy workaround is present.
          • Resolved
          is required by

          Bug - A problem which impairs or prevents the functions of the product. NXP-29025 Fix original component on operation chain

          • Minor - Minor loss of function, or other problem where easy workaround is present.
          • Resolved

          Task - A task that needs to be done. NXP-19497 Review Platform Explorer styles and UX

          • Minor - Minor loss of function, or other problem where easy workaround is present.
          • Resolved
          Is referenced in

          [Captain Hook] PR for master: #62 PR for master: #62

          [Captain Hook] PR for master: #4078 PR for master: #4078

          [Captain Hook] PR for master: #4107 PR for master: #4107

            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