Transmogrify rst documentation files to md

[jwnimmer-tri]

Our transition plan for #13832 is to commit a draft of the new Drake website to our master branch (using pull requests, as usual), alongside the current site. The rst files will remain for the old site, and the md files will be added for the new site. The CI pipeline already deploys both at once, with the new site under a /jekyll subdirectory. We can use that to integration-test the new site.

Once the new site preview is looking good, we will swap the deployment pipeline to publish the new site at the root. After a couple days after the revert hazard has passed, we'll remove the old rst files from master.

Our starting point(s) for the markdown content will be the following:

(1) #14479 has an incomplete draft of this rst2md work, but also had various styling changes and javascript packages also in the diffs.

(2) In the DrakeDevelopers slack channel #website, there is an attachment named drake-site-102820.zip, which also has a draft of the whole site in markdown, from the original website contractors. This is probably superseded by (1), but might still be a helpful reference.

The goal here is that we have an open PR against Drake that adds the transmogrified markdown files, but does not add any of the styling sidecars or javascript jiblets. We use that PR to do a careful code review that all of the rst prose on currently master makes it into the pull request md prose, and that the website preview does not crash jekyll, and then we merge that to master.

• If convenient, we could imagine doing several PRs each converting some of the rst files, instead of one giant PR. Either way is fine. In any case, we should have a small handful (4?) or reviewers look over the markdown files, not just one person.
• Notably, the drafts at (1) and (2) above were taken from older git commits of the rst text currently on master, so we definitely need to forward-patch them with the recent prose changes.

From that point on (for a transition period of a couple weeks), Drake's platform reviewers will ensure that any pull requests that change the rst prose also reflect the same change into the md prose. (For our convenience, we'll also discourage rst changes in the first place, unless they are urgent.)

It is not a prerequisite of the rst => md transmogrification PRs that the markdown site look any good. We only care that all of the words make it over. As we find presentation defects in the markdown styling, we can PR those independently to master, prior to making the site live. We don't need those presentation fixes (and should not focus on those fixes) during the simple text-conversion PR(s).

TL;DR: Get the markdown prose committed to master, paying particular attention that we do not lose any rst prose during the file copy, so that we can iterate on style and layout without worrying about losing text.

[ggould-tri]

This sounds right to me; our objective is to make an initial PR that consists only of formatting changes and which appears as much as possible perfectly mechanical.

FYI @SeanCurtis-TRI

[ggould-tri]

(Also just to be clear, the resulting diff might be sane in reviewable as a copy revision and a diff revision, or it might require offline review with semantic diff tools; in the (more likely) latter case we will select reviewers who are comfortable with such tools)

[jamiesnape]

We have the markdown converted to rst already, but if you want to reinvent the wheel that is fine.

[ggould-tri]

I don't expect to reinvent the wheel; I hope that this issue in practice is just a matter of structuring what you already have in easily reviewable form.

[jamiesnape]

I think Betsy even minimized the diff between each page and its rst original, so I will ping you when she is able to push the latest complete branch, which may have disappeared in the back and forth of the various PR's.

[jamiesnape]

Probably the commits to doc from release notes for v0.26.0 onwards is all you really need to do yourself.

[BetsyMcPhail]

The branch with all of my changes is available here .

The branch was created around January 12th, so there will be some updates that need to be made.

For most files, a diff between the md and rst should be straightforward.

Of note:

• In the source provided by the original website contractors, the developers page was split into multiple pages in order to create a table of contents. This looked nice but was not maintainable. In the jekyll-website branch, developers is back to a single page with no table of contents.
• Similarly, the index page has been split into multiple documents within the _homeblocks directory. This is in a separate commit.

[EricCousineau-TRI]

Additional action item:

• Synchronize #14646

[ggould-tri]

TODO items remaining, actionable now (update this as git log docs/ shows changes):

• [x] update md for #14646
• ~[ ] Rescue _homeblocks directory from @BetsyMcPhail 's branch (link above is broken; need a new branch link)~ Rejected this idea.

TODO after jekyll rendering is working:

• [x] Fix any broken jekyll headmatter on md files.

  EDIT(eric): Add'l candidates. I can help with them.

  • [x] update md for #14660
  • [x] update md for https://github.com/robotlocomotion/drake/pull/14651

[jamiesnape]

You should be able to create a single markdown file in _homeblocks with just

---
title: Random Title
---

Random content.

and I think it will at least unblock the build.

[jamiesnape]

Actually, the original files were just chunks of the previous main page. I can create them for you if @EricCousineau-TRI does not have a copy.

[jwnimmer-tri]

I think #14479 still has a copy. The personal branch was deleted, but the pull request still has all the content. There's also (in the #website slack channel) the original zipfile from the contractors to use for reference.

[jamiesnape]

I do not think @BetsyMcPhail changed anything, but even if she did, the originals should still work.

[BetsyMcPhail]

I didn't change anything of substance in the _homeblocks directory.

[EricCousineau-TRI]

I can do a skeleton _homeblocks PR.

Not loving what the file organization looks like, but may give up shortly.

[EricCousineau-TRI]

Actually, scratch all that. I'd suggest waiting until I have the PR ready.

(I just have two more items left - simplify TOC-style logic, and minimize directory tree differences, 'cause the current setup is still a tad confusing.)

[jwnimmer-tri]

@ggould-tri Is this issue ready to close?

It looks like "Fix any broken jekyll headmatter on md files." is the only item not checked off.

[ggould-tri]

Yes, I believe that with #14687 we are where we need to be: Future edits will have a reasonably working rendered world in hand that is up-to-date with the markdown world; transition to Jekyll is now primarily aesthetic rather than content work.