Jump to: navigation, search

Documentation/Tools/reStructuredText

Benefits

  • Unify the docs into a single location. At the moment, the Boron getting-started-guide and openstack-guide are in one location, while the user-guide and developer-guide are in another location. It would be nice to have it all under [docs.opendaylight.org docs.opendaylight.org].
  • The user experience is more intuitive and easier to navigate. There are some added benefits from the expanded feature set.
    • In particular, the ability to rapidly switch between the documentation for different releases by seamlessly interpreting git branches as different releases.
    • Also the the ability to flag some releases as unsupported, old, or insecure.
  • There is more community support and activity with the reStructuredText/Sphinx/Read the Docs toolchain as compared to AsciiDoc/Asciidoctor, including from the Python community.
  • Empower individual projects to take ownership of their documentation by pushing the user-guide and developer-guide into project repositories. This can scale much more efficiently as the number of projects grows in OpenDaylight.

Usages

Resources

ReStructuredText Boron Migration Tasks

  • Communicate our intention with the TSC and ensure no serious objections from this migration effort to occur in the Boron time frame.
    • Responsible: <colin>
  • Communicate our plans with the projects and documentation contacts and track acknowledgement from projects.
  • Update the “Boron Documentation Requirements” [1] with the appropriate content so developers understand the new procedure/process for submitting documentation.
  • Update the “Boron Simultaneous Release Plan” [2] with the appropriate content.
  • Update the “Docs Boron Release Plan” [3] to communicate our migration efforts.
  • For each project, convert old AciiDoc user-guide and developer-guide into reST and submit patches into docs git repository.
  • For each project, remove the old AsciiDoc user-guide and developer-guide.
  • For each project, move reST user-guide and developer-guide and submit patches into individual project git repository.
  • For each project, remove reST user-guide and developer-guide.
  • For each project, convert pending AsciiDoc patches to reST and submit those patches into the respective git repository.
  • For each project, abandon the pending AsciiDocs patches.