TSC approved the migration of the Doc repo away from using git submodules to using intersphinx linking instead TSC 2020-01-30

Background information

 

Steps to migrate to new docs

General steps look similar to OPNFV migration https://docs.opnfv.org/en/latest/how-to-use-docs/local-build-transition.html

We are working on an ONAP module to use as test to identify the exact code and changes needed to be done that fit the current ONAP structure.

Migration Status


Current Action by PTLs Needed

PTLS ACTION ITEM

Please review the new docs in https://onap-doc.readthedocs.io/en/latest/ 

A link for all active projects has been added here: https://onap-doc.readthedocs.io/en/latest/guides/active-projects/index.html

IF sanity testing on the docs looks ok, please respond "PASS" in the "Sanity Check by PTL" column below

Changes merged

TaskCreate individual docs per submoduleReview-approve

Update intersphinx linking

(Refer to "Next Steps"  ppt attached

Sanity check by PTL

Remove old submodule from doc repo
ResponsibleRelEngPTL

RelEng
Estimated Duration




AAF

https://gerrit.onap.org/r/#/c/aaf/authz/+/101298/

https://gerrit.onap.org/r/#/c/aaf/sms/+/101286/

Changes merged

Add common labels to the docs to standardize all:



AAI

https://gerrit.onap.org/r/#/c/aai/event-client/+/101335/

https://gerrit.onap.org/r/#/c/aai/sparky-be/+/101314/

https://gerrit.onap.org/r/#/c/aai/esr-gui/+/101313/

https://gerrit.onap.org/r/#/c/aai/aai-common/+/101312/

https://gerrit.onap.org/r/#/c/aai/esr-server/+/101310/

Changes merged

APPC

https://gerrit.onap.org/r/#/c/appc/deployment/+/101295/

https://gerrit.onap.org/r/#/c/appc/+/101291/

Changes mergedPASS
CCSDK

https://gerrit.onap.org/r/#/c/ccsdk/apps/+/101350/

https://gerrit.onap.org/r/#/c/ccsdk/cds/+/101351/

https://gerrit.onap.org/r/#/c/ccsdk/platform/plugins/+/101320/

https://gerrit.onap.org/r/#/c/ccsdk/dashboard/+/101318/

https://gerrit.onap.org/r/#/c/ccsdk/features/+/101353/

https://gerrit.onap.org/r/#/c/ccsdk/distribution/+/101319/

Changes mergedPASS
CLAMPhttps://gerrit.onap.org/r/#/c/clamp/+/101294/Changes merged

CLIhttps://gerrit.onap.org/r/#/c/cli/+/101293/Changes mergedPASS
DCAEhttps://gerrit.onap.org/r/#/c/dcaegen2/+/101297/Changes mergedPASS
DMAAP

https://gerrit.onap.org/r/#/c/dmaap/buscontroller/+/101346/

https://gerrit.onap.org/r/#/c/dmaap/dbcapi/+/101338/

https://gerrit.onap.org/r/#/c/dmaap/datarouter/+/101337/

https://gerrit.onap.org/r/#/c/dmaap/messagerouter/messageservice/+/101309/

Changes merged

PASS


DocumentationN/AN/A

Some editorial impacts due to the new links.

Bullet lists disapperared:

https://onap-doc.readthedocs.io/en/latest/guides/onap-developer/apiref/index.html

https://onap-doc.readthedocs.io/en/latest/guides/onap-provider/index.html

=> https://gerrit.onap.org/r/c/doc/+/108233



ExtAPIhttps://gerrit.onap.org/r/#/c/externalapi/nbi/+/101341/Changes merged

Holmes

https://gerrit.onap.org/r/#/c/holmes/rule-management/+/101301/

https://gerrit.onap.org/r/#/c/holmes/engine-management/+/101302/

Changes merged



Integrationhttps://gerrit.onap.org/r/#/c/integration/+/101315/Changes merged

Problem with image formats

https://onap-doc.readthedocs.io/projects/onap-integration/en/latest/index.html#master-index


Jessica says: I noticed that the images are rendered at 100% scale. Shall we reduce them to 70% to make them fit better? I am not sure if we can otherwise make the page expand in general to accommodate them better. Do you guys know if we can do that? 

Eric Debeau As explained in the note under this table : Display impact detected on https://onap-doc.readthedocs.io/

We must expand the div displaying the content.


Jessica says: I tried doing something like this but it didn't worked: https://gerrit.onap.org/r/c/integration/+/107585

I also was reading more about the limits set in docs/_static/css/ribbon.css, but not sure if I should modify anything there. I am not sure which note do you refer to sorry.. all I can see in that page is the table fixed to that certain width.


Logging

https://gerrit.onap.org/r/#/c/logging-analytics/pomba/pomba-audit-common/+/101348/

https://gerrit.onap.org/r/#/c/logging-analytics/+/101332/

Changes merged

Modeling

https://gerrit.onap.org/r/#/c/modeling/etsicatalog/+/101355/

https://gerrit.onap.org/r/#/c/modeling/toscaparsers/+/101333/

https://gerrit.onap.org/r/#/c/modeling/modelspec/+/101308/

Changes mergedPASS
MSB

https://gerrit.onap.org/r/#/c/msb/discovery/+/101305/

https://gerrit.onap.org/r/#/c/msb/apigateway/+/101304/

https://gerrit.onap.org/r/#/c/msb/swagger-sdk/+/101307/

https://gerrit.onap.org/r/#/c/msb/java-sdk/+/101306/

Changes merged



MultiCloud

https://gerrit.onap.org/r/#/c/multicloud/k8s/+/101317/

https://gerrit.onap.org/r/#/c/multicloud/framework/+/101316/

https://gerrit.onap.org/r/#/c/multicloud/azure/+/101345/

Changes merged

Music

https://gerrit.onap.org/r/#/c/music/distributed-kv-store/+/101342/

https://gerrit.onap.org/r/#/c/music/+/101340/

Changes merged



OOF

https://gerrit.onap.org/r/#/c/optf/cmso/+/101347/

https://gerrit.onap.org/r/#/c/optf/osdf/+/101336/

https://gerrit.onap.org/r/#/c/optf/has/+/101296/

Changes merged

OOMhttps://gerrit.onap.org/r/#/c/oom/+/101311/Changes mergedPASS
O-parent

https://gerrit.onap.org/r/#/c/oparent/cia/+/101349/


Changes merged

Policy

https://gerrit.onap.org/r/#/c/policy/parent/+/101354/

https://gerrit.onap.org/r/#/c/policy/engine/+/101299/

Changes merged

FAIL - policy/parent link is missing

https://onap-doc.readthedocs.io/en/latest/guides/onap-developer/developing/index.html#policy-framework

Jessica says: Pamela Dragosh  Jorge Hernandez  This change removed the needed doc labels and reverted part of the automation behind it:

https://gerrit.onap.org/r/c/policy/parent/+/106383

Can you guys please re-visit it?

Jessica Wagantall  - we are fixing label errors as requested by the Documentation team:

POLICY-2511 - Getting issue details... STATUS

Which label are you talking about specifically? Perhaps ask Thomas Kulik to relax his warnings checking for specific labels needed for this effort. We simply would not know what needs to stay - perhaps you should add a comment with the label.



Portalhttps://gerrit.onap.org/r/#/c/portal/+/101322/Changes merged

SDC

https://gerrit.onap.org/r/#/c/sdc/sdc-workflow-designer/+/101327/

https://gerrit.onap.org/r/#/c/sdc/sdc-distribution-client/+/101324/

https://gerrit.onap.org/r/#/c/sdc/sdc-tosca/+/101326/

https://gerrit.onap.org/r/#/c/sdc/sdc-docker-base/+/101325/

https://gerrit.onap.org/r/#/c/sdc/+/101323/

Changes merged




SDNC

https://gerrit.onap.org/r/#/c/sdnc/oam/+/101321/


Changes mergedPASS
SO

https://gerrit.onap.org/r/#/c/so/libs/+/101331/

https://gerrit.onap.org/r/#/c/so/+/101330/

Changes merged

UUIhttps://gerrit.onap.org/r/#/c/usecase-ui/+/101329/Changes merged

VFC

https://gerrit.onap.org/r/#/c/vfc/nfvo/driver/vnfm/svnfm/+/101339/

https://gerrit.onap.org/r/#/c/vfc/nfvo/lcm/+/101303/

Changes merged

PASS


VIDhttps://gerrit.onap.org/r/#/c/vid/+/101328/Changes mergedPASS

VNFSDK

https://gerrit.onap.org/r/#/c/vnfsdk/model/+/101300/Changes mergedPASS
VVPhttps://gerrit.onap.org/r/#/c/vvp/documentation/+/101334/Changes mergedPASS

@


Notes


Update as of April 07

Display impact detected on https://onap-doc.readthedocs.io/


  • The screen to display the content (div .wy-nav-content) is limited to 800px for the various projects  (default CSS configuration by Sphinx) while the previous value was fixed to unlimited as configured in ribbon.css => https://git.onap.org/doc/tree/docs/_static/css
  • Need to align the Documentation project CSS with project CSS. Currently, there is no CSS in the various project directory while the conf.py includes a css link cf https://git.onap.org/oom/tree/docs/conf.py and no CSS file is not part of the project
    defsetup(app): app.add_stylesheet("css/ribbon_onap.css")













4 Comments

  1. Trevor Lovett

    Once integrated, will the RTD URLs change?  For example, if external sites or material is pointing to https://onap.readthedocs.io/en/latest/submodules/vnfrqts/requirements.git/docs/index.html  will the content now live at a new URL?  If so, what will visitors to the old URL experience (redirect to somewhere, etc.)?

    1. Jessica Wagantall

      I will need to get all the details from Aric after the next step is addressed. It might be a different location, but I am not 100% sure yet. Will get back to you after checking with him

  2. Sofia Wallin

    The URLs will change, see example, https://docs.opnfv.org/en/stable-fraser/submodules/fuel/docs/release/installation/index.html#fuel-installation

    AND

    https://opnfv-fuel.readthedocs.io/en/latest/release/installation/index.html#fuel-installation

    I'm not sure if it's possible to redirect. If anyone searches for ONAP documentation they will end up on the default version which is the latest release, and that is not related to this migration. I do believe that the old link won't work, so it's a valid question.

    Maybe Trevor Bramwell or Jessica Wagantall can answer that?

  3. Jessica Wagantall

    Sofia Wallin Could you please comment on Krzys question? 

    https://gerrit.onap.org/r/#/c/oom/+/101311/ Do you think this might be an issue?