Opened 7 years ago
Closed 7 years ago
#14015 closed enhancement (fixed)
Convert develop/packages docs to reStructuredText
Reported by: | leorize | Owned by: | waddlesplash |
---|---|---|---|
Priority: | normal | Milestone: | Unscheduled |
Component: | Documentation | Version: | R1/Development |
Keywords: | Cc: | ||
Blocked By: | Blocking: | ||
Platform: | All |
Description
The MediaWiki syntax used by the docs have several problems:
- Unable to have more than one paragraph per list items. This is relied upon by Bootstrapping, and BuildingPackages
- Hard wrapping can't be done globally as lists end on new line
- Heavy reliance on HTML tags, a side effect of this is that all HTML symbols has to be escaped
Markdown was considered as an alternative, but:
- Still rely on HTML tags for tables and ToC (Table of Contents). Github Flavoured Markdown solve tables, but not ToC
- ToC has to be written by hand
-
,_
has to be escaped, which renders Markdown unsuitable for the docs, namely Bootstrapping, Migration, HybridBuilds, ...- Definition lists can't be converted without losing schematic, used by FileFormat
reStructuredText however, provides:
- Markdown-like syntax, easy to read and edit
- No reliance on HTML tags, nor could you use them within the docs
- ToC generator
The rendered rST version could be found here. It should be comparable to PackageManagement
Change History (2)
comment:1 by , 7 years ago
Owner: | changed from | to
---|---|
Status: | new → in-progress |
comment:2 by , 7 years ago
Resolution: | → fixed |
---|---|
Status: | in-progress → closed |
Note:
See TracTickets
for help on using tickets.
Merged in hrev51832. Thanks!