[DRIVERS-2789] Use Markdown for Specifications Documentation Created: 05/Dec/23 Updated: 07/Feb/24 |
|
| Status: | Designing |
| Project: | Drivers |
| Component/s: | None |
| Fix Version/s: | None |
| Type: | Epic | Priority: | Unknown |
| Reporter: | Steve Silvester | Assignee: | Steve Silvester |
| Resolution: | Unresolved | Votes: | 0 |
| Labels: | None | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original Estimate: | Not Specified | ||
| Issue Links: |
|
||||
| Driver Changes: | Not Needed | ||||
| Quarter: | FY25Q1 | ||||
| Start date: | |||||
| End date: | |||||
| Calendar Time: | 4 weeks, 3 days | ||||
| Scope Cost Estimate: | 0 | ||||
| Cost to Date: | 0 | ||||
| Final Cost Estimate: | 0 | ||||
| Cost Threshold %: | 100 | ||||
| Detailed Project Statuses: | 2024-02-02
|
||||
| Description |
SummaryUpdate our drivers specification source documents to use Github Flavored Markdown. MotivationFollowing up on DRIVERS-983, there is a renewed concern that is it prohibitively difficult to use RST. Additionally, there is a new internal initiative to use Pine for R&D docs, which consumes Github Flavored Markdown. ProposalWe can use pandoc and a custom script to most of the heavy lifting to convert the existing RST documents to Markdown. Each spec author would be tasked with running the script and ensuring that the resulting document(s) are correct. We have verified that GitHub Flavored Markdown accommodates all of the features we were using in RST, except for the fact that Admonitions (e.g. inline warning box) are not uniformly specified. Docusaurus (which is used by Pine) has one syntax, while GitHub recently standardized another. We should prioritize rendering on Docusaurus in this case, since the drivers and other internal teams will most commonly use the rendered documentation. As a pilot, I will make a PR to add the script and convert the CSOT specification. Once that is done, we can open the other child tickets on this Epic for each spec. Once we have about a half dozen specs, we can turn on the Pine integration (which will be its own child ticket), as a carrot for everyone to update their specs. Implementation PlanI will run the migration script and open the PRs, in order to avoid merge conflicts. I will ping the spec owners for review.
Cast of CharactersEngineering Lead: Channels & DocsSlack Channel[Scope Document|some.url][Technical Design Document|some.url] |
| Comments |
| Comment by Githook User [ 07/Feb/24 ] |
|
Author: {'name': 'Steven Silvester', 'email': 'steven.silvester@ieee.org', 'username': 'blink1073'}Message: DRIVERS-2789 Convert Auth Spec to Markdown (#1501)
|
| Comment by Githook User [ 06/Feb/24 ] |
|
Author: {'name': 'Steven Silvester', 'email': 'steven.silvester@ieee.org', 'username': 'blink1073'}Message: DRIVERS-2789 Convert Benchmarks Spec to Markdown (#1498)
|
| Comment by Githook User [ 31/Jan/24 ] |
|
Author: {'name': 'Steven Silvester', 'email': 'steven.silvester@ieee.org', 'username': 'blink1073'}Message: DRIVERS-2789 Convert CMAP Spec to Markdown (#1500)
|
| Comment by Githook User [ 23/Jan/24 ] |
|
Author: {'name': 'Steven Silvester', 'email': 'steven.silvester@ieee.org', 'username': 'blink1073'}Message: DRIVERS-2789 Convert BSON Corpus Spec to Markdown (#1499) |
| Comment by Githook User [ 04/Jan/24 ] |
|
Author: {'name': 'Steven Silvester', 'email': 'steven.silvester@ieee.org', 'username': 'blink1073'}Message: DRIVERS-2789 Use Markdown for Specifications Documentation (#1482)
This reverts commit f30793e0e4e70595f3ba8945256060fee89aca04.
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
Co-authored-by: Jeremy Mikola <jmikola@gmail.com>
--------- Co-authored-by: Jeremy Mikola <jmikola@gmail.com> |
| Comment by Steve Silvester [ 21/Dec/23 ] |
|
I changed it to Designing. Once the initial PR is merged I'll make the tickets for spec owners and move it to Teams Implementing. |