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
@
Notes
Update as of April 07
- All Changes merged now to add each project's config
- Attached Next Steps ppt describing what we need to do next
- We are working to add a new index label that is common across all repos
- This is just for consistency and to make thing easier
- Example: https://gerrit.onap.org/r/c/oom/offline-installer/+/105199/2/docs/index.rst
- All changes: https://gerrit.onap.org/r/q/owner:releng%252Blf-jobbuilder%2540linuxfoundation.org+status:open
- Need to ask the team if we can mass merge these for making it easier
- Internal links should be converted to intersphinx ones
- Example: https://gerrit.onap.org/r/c/doc/+/105175
- We are looking into how to make this task fast and put some instructions on what to do so that we can have some volunteers helping
- There are aprox 300 links to fix
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
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.)?
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
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?
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?