[Eden Diary_TD] Eden Docs and reStructuredText by Jay Lee

Eden Docs and reStructuredText
by Jay Lee

The Eden team has been very busy with the upcoming mainnet launch. We decided that one of the best ways to showcase what we have been preparing for is to release documents. There are many ways to publish documents — either converting and sharing them into PDF format or directly sharing them on our official EdenChain website. In order to allow many people to read the documents across multiple access environments, we decided to convert the documents we created with reStructuredText to HTML using Sphinx. reStructuredText (rST) is a markup language that is widely used for documenting technical content and has been officially adopted by and used in Python Document.

In this blog, I would like to briefly introduce the features of the rST language, which has the advantage of being able to create documents and to use them without knowledge of the markup language.

Characteristics of rST

• Readable: The raw-form should be easy to read without any knowledge of the markup language.
• Unobtrusive: Grammar should be as simple and straightforward as possible.
• Unambiguous: The grammar must not be ambiguous, and one input form must appear as a single output form.
• Unsurprising: It should consist of expected results.
• Intuitive: It should be easy to remember by virtue of a clear, underlying, grammar.
• Easy: It should be easy to write in any text editor.
• Scalable: It should not be affected by the amount of text.
• Powerful: An editor should provide enough grammar for documentation.
• Language-neutral: It should support all languages in addition to English.
• Extensible: Adding complex or custom markups should be easy.
• Output-format-neutral: It must support a variety of output formats, rather than just specific formats.

rST is used as a “rule-relaxed document” that uses a consistent pattern. The completed rST document can be uploaded to Github, etc., or converted to HTML using Sphinx. At first, it may seem difficult due to its unfamiliar rules. However, I believe anyone can easily adapt to the language more quickly than they might expect.

This is the quick-start document for rST for your reference: http://docutils.sourceforge.net/docs/user/rst/quickstart.html

Studying the rST format in preparation for Eden Docs has not been difficult. It allowed me to write intuitively, like other markup languages, and once I became familiar with the few rules that I used repeatedly, I was able to write documents quickly. The problem I faced, however, was to change the existing Eden documents to rST format!

There are already many tools to convert documents to rST documents. Since existing documents are written in various formats using different types of templates, however, blindly converting them to rST can, for example, deform the table of contents in the document or result in spacing that does not match the original.

As a result of various tests I have found that the conversion of an MS Word document (docx) to rST yields something most similar to the original, that the converted rST contents are very intuitive, and that the document size is actually shortened. Fortunately, the document collaboration system used by EdenChain is available to export to Word, so that existing documents can be converted to rST with minimal effort.

• How to Convert Variable-Format Document to rST

1. Export the existing document to Word (docx)
2. Unify indented symbols represented by various symbols in a Word document with one symbol (-) and delete vertical cell merging of the table
3. Convert Word document to rST with Pandoc (Converter Tool)
4. Review converted rST document
5. Convert to HTML using Sphinx

(the process of reviewing a document converted to rST)

I hope this blog will be helpful for people who are planning to convert a document to reStructuredText format.