Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-3863

Web design fixes DM Design Documents on Sphinx/Read The Docs

    XMLWordPrintable

    Details

    • Type: Story
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: Design Documents
    • Labels:
      None

      Description

      Solve fit-and-finish issues with the stock readthedocs.org Sphinx template when rendering DM design documents. Issues include:

      • Sections need to be numbered and those numbers need to appear in TOC
      • RTD's TOC does not properly collapse sub-topics
      • Appropriate styling for document title and author list
      • Wrapping the changelog table
      • Adapt section references so that just the section number can be referenced, independently of the section number and title in combination
      • Section labels given explicitly in the reST markup are different from the anchors that Sphinx gives to the {{<hN>}}tags; the former are simply divs inserted in the HTML.

      The solutions may involve

      1. reconfiguring the Sphinx installation of individual documents
      2. forking the RTD HTML template, and/or
      3. developing extensions for Sphinx in sphinxkit.

        Attachments

          Issue Links

            Activity

            Hide
            jsick Jonathan Sick added a comment -

            The numbering issues are mostly solved by using the .. sectnum directive of docutils, but this isn't officially supported by Sphinx. Remanding issues are

            1. Read the Docs has a broken sidebar table of contents that does not collapse sub sections are the UI would indicate
            2. No flexibility in choosing whether an internal references a) includes the section number only, or b) includes the title only.

            Show
            jsick Jonathan Sick added a comment - The numbering issues are mostly solved by using the .. sectnum directive of docutils, but this isn't officially supported by Sphinx. Remanding issues are 1. Read the Docs has a broken sidebar table of contents that does not collapse sub sections are the UI would indicate 2. No flexibility in choosing whether an internal references a) includes the section number only, or b) includes the title only.
            Hide
            jsick Jonathan Sick added a comment -

            Regarding issue with Sphinx section labels, I've posted to the Sphinx Google Group

            https://groups.google.com/forum/#!topic/sphinx-users/LO83SCYKm4Q

            Show
            jsick Jonathan Sick added a comment - Regarding issue with Sphinx section labels, I've posted to the Sphinx Google Group https://groups.google.com/forum/#!topic/sphinx-users/LO83SCYKm4Q
            Hide
            jsick Jonathan Sick added a comment -

            Work was accomplished by forking the RTD Sphinx theme and customizing the Jinja2 templates and SASS to suite the design documents.

            See https://github.com/lsst-sqre/lsst_dd_rtd_theme

            Show
            jsick Jonathan Sick added a comment - Work was accomplished by forking the RTD Sphinx theme and customizing the Jinja2 templates and SASS to suite the design documents. See https://github.com/lsst-sqre/lsst_dd_rtd_theme

              People

              Assignee:
              jsick Jonathan Sick
              Reporter:
              jsick Jonathan Sick
              Watchers:
              Jonathan Sick
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Jenkins Builds

                  No builds found.