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

Convert Confluence DM Developer Guide to Sphinx (hack day)

    Details

      Description

      This is a hack day sprint to convert all remaining content on https://confluence.lsstcorp.org/display/LDMDG to reStructuredText content in the Sphinx project at https://github.com/lsst-sqre/dm_dev_guide and published at http://developer.lsst.io.

      The top priority for this sprint is to port all content into reST and have it tracked by Git.

      Sprint ground rules

      1. Before the sprint, clone https://github.com/lsst-sqre/dm_dev_guide.git and pip install -r requirements.txt in a Python 2.7 environment so that you can locally build the docs (make html).
      2. Claim a page from the list below by putting your name on it. Put a checkmark on the page when you’ve merged it to the ticket branch (see below).
      3. See http://developer.lsst.io/en/latest/docs/rst_styleguide.html for guidance on writing our style of reStructuredText. Pay attention to the heading hierarchy and labelling for internal links.
      4. If you use Pandoc to do an initial content conversion, you still need to go through the content line-by-line to standardize the reStructuredText. I personally recommend copy-and-pasting-and-formatting instead of using Pandoc.
      5. Your Git commit messages should include the URL of the original content from Confluence.
      6. Merge your work onto the tickets/DM-5013 ticket branch. Rebase your personal work branch before merging. JSick is responsible for merging this ticket branch to master.
      7. Put a note at the top of the confluence page with the new URL; root is http://developer.lsst.io/en/latest/.

      Planned Developer Guide Table of Contents

      We’re improving the organization of DM’s Developer Guide; there isn’t a 1:1 mapping of Confluence pages to developer.lsst.io pages. Below is a proposed section organization and page structure. These sections can still be refactored based on discussion during the hack day.

      Getting Started — /getting-started/

      • Onboarding Checklist (Confluence: Getting Started in DM). I’d like this to eventually be a quick checklist of things a new developer should do. It should be both a list of accounts the dev needs to have created, and a list of important developer guide pages to read next. The NCSA-specific material should be spun out. [Jonathan Sick]
      • Communication Tools (new + DM Confluence Communication and Links). I see this as being an overview of what methods DM uses to communicate, and what method should be chosen for any circumstance.
      • Finding Code on GitHub (new). This should point out all of the GitHub organizations that a developer might come across (DM and LSST-wide), and point out important repositories within each organization. Replaces the confluence page LSST Code Repositories

      Processes — /processes/

      Coding Guides — /coding/

      Writing Docs — /docs/

      • Introduction (new): Overview of DM’s documentation needs; links resources on technical writing.
      • English Style Guide (new): Supplement the LSST Style Manual and provide English style guidance specific to DM. Capitalization of different heading levels; use of Chicago Manual of Style; a ‘this, not that’ table of spelling and word choices.
      • ReStructuredText Style Guide (new)
      • Documenting Stack Packages (new)
      • Documenting Python Code (new)
      • Documenting C++ Code (confluence, adapted from Documentation Standards); needs improvement
      • Writing Technotes (new; port README from lsst-technote-bootstrap)

      Developer Tools — /tools/

      • Git Setup and Best Practices (new)
      • Using Git Large File Storage (LFS) for Data Repositories (new)
      • JIRA Work Management Recipes (new)
      • Emacs Configuration (Confluence). See DM-5045 for issue with Emacs config repo - Jonathan Sick
      • Vim Configuration (Confluence) - Jonathan Sick

      Developer Services — /services/

      Build, Test, Release — /build-ci/

      • Creating a new DM Stack Release (confluence); though this page or a modern equivalent should probably belong with the software docs? Frossie Economou

      A lot of work should go into this section. Have something about Scons? Or maybe that belongs in the doc of each relevant software product.

      Leftover Confluence pages

      The following pages should be moved to a separate Confluence space run by NCSA:

      The following pages are either not relevant, generally misplaced, or need to be updated/recalibrated:

        Attachments

          Issue Links

            Activity

            Hide
            jsick Jonathan Sick added a comment -

            Frossie Economou and John Swinbank: I’m going to try rebasing tickets/DM-5013 onto the new master. Hold off on using the tickets/DM-5013 branch for now in case things get messy.

            Show
            jsick Jonathan Sick added a comment - Frossie Economou and John Swinbank : I’m going to try rebasing tickets/ DM-5013 onto the new master. Hold off on using the tickets/ DM-5013 branch for now in case things get messy.
            Hide
            jsick Jonathan Sick added a comment -

            I’ve rebased and force-pushed tickets/DM-5013 against master.

            Be sure to use the new tickets/DM-5013 from GitHub and rebase any un-merge work branches against this one.

            Show
            jsick Jonathan Sick added a comment - I’ve rebased and force-pushed tickets/ DM-5013 against master. Be sure to use the new tickets/ DM-5013 from GitHub and rebase any un-merge work branches against this one.
            Hide
            frossie Frossie Economou added a comment -

            Using the Redirection plugin (licensed but free) which provides a macro to forward from removed Confluence content to the new location. Eventually the pgaes can be removed completely.

            Show
            frossie Frossie Economou added a comment - Using the Redirection plugin (licensed but free) which provides a macro to forward from removed Confluence content to the new location. Eventually the pgaes can be removed completely.
            Hide
            jsick Jonathan Sick added a comment -

            Sprint is complete, all relevant pages from the DM Developer Guide on Confluence have been ported over. Tickets will be made for new developer guide additions and migration of relevant content in the DM confluence space as well as Trac.

            Show
            jsick Jonathan Sick added a comment - Sprint is complete, all relevant pages from the DM Developer Guide on Confluence have been ported over. Tickets will be made for new developer guide additions and migration of relevant content in the DM confluence space as well as Trac.
            Hide
            swinbank John Swinbank added a comment -

            What's the status on redirection? The few pages I checked on Confluence are not migrating to the new docs – should they all now be doing so or is that still a work in progress?

            Show
            swinbank John Swinbank added a comment - What's the status on redirection? The few pages I checked on Confluence are not migrating to the new docs – should they all now be doing so or is that still a work in progress?

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                jsick Jonathan Sick
                Watchers:
                Frossie Economou, John Swinbank, Jonathan Sick, Kian-Tat Lim, Tim Jenness
              • Votes:
                0 Vote for this issue
                Watchers:
                5 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel