[WIP] Caster Quick Reference as restructured text

[sovoid]

Title

Caster Quick Reference as restructured text

Description

This PR is an attempt to convert the existing documentation in the Caster Quick Reference guide from LaTeX to restructured text

Related Issue

Closes #629

Motivation and Context

As mentioned in #629, using LaTeX for documentation poses challenge not just for new users but even for seasoned users. We want to replace the existing documentation from LaTeX to a more easy to grasp syntax like markdown or restructured text, both of which are also understood and rendered by Github Markdown as an additional plus

How Has This Been Tested

This PR has been tested using the reStructuredText VSCode extension

OS: Windows 10 Home

This change only affects the docs

Types of changes

• [x] Docs change / refactoring / dependency upgrade

Checklist

• [x] I have read the CONTRIBUTING document.
• [ ] My code follows the code style of this project.
• [x] I have checked that my code does not duplicate functionality elsewhere in Caster.
• [ ] My code implements all the features I wish to merge in this pull request.
• [x] My change requires a change to the documentation.
• [ ] I have updated the documentation accordingly.
• [ ] I have added tests to cover my changes.
• [ ] All new and existing tests pass.

Maintainer/Reviewer Checklist

• [ ] Basic functionality has been tested and works as claimed.
• [ ] New documentation is clear and complete.
• [ ] Code is clear and readable.

[sovoid]

@LexiconCode i tried running Pandoc on the CasterQuickReference.tex file however the formatting seems to not be right since the preview does not get rendered correctly. I have used markdown before but am new to restructured text, could you take a look and help me out?

[LexiconCode]

@LexiconCode i tried running Pandoc on the CasterQuickReference.tex file however the formatting seems to not be right since the preview does not get rendered correctly. I have used markdown before but am new to restructured text, could you take a look and help me out?

I would be glad to take a look. A quick peek at the moment. rst.pdf

rendered using http://rst.ninjs.org

It'll be a couple days before I can take a more in depth look as I'm finishing up some night shifts.

[sovoid]

@LexiconCode agreed the formatting seems clearly off from the expected. Please take your time to review this. Let me know if you have any pointers on how the formatting can be fixed.

[sovoid]

Hey @LexiconCode just curious if you got a chance to look at the PR?

[LexiconCode]

Hey @LexiconCode just curious if you got a chance to look at the PR?

I have an after spending quite a bit of time trying to fight restructured text to get columns right. In part this is due to crappy editors. I thought of a different approach that I mentioned an issue that this PR references. Basically using Microsoft Word/LibreOffice to create a word document with the appropriate columns and footings. This will be much easier to use and maintain over the long term. We can easily convert those files to PDFs and I also included an issue a method to allow git to diff for documents.

[LexiconCode]

Hey @LexiconCode just curious if you got a chance to look at the PR?

Sorry for the delay I will be taking the next couple of days to try to hammer out one way or the other how to help you through this.

[sovoid]

@LexiconCode no worries please take your time 🙂...gives me enough time to understand the docs

[LexiconCode]

@ und3fined-v01d here's an example. 1st an editor. retext is simple but Is only one I could find it's reasonably up-to-date. pip install ReText and launch the command line using ReText.

An example document

Caster Quick Reference
======================

+----------------------------------+
|\1. Numbers                       |
+==================================+
|numb <0...1m> print digits [e]_   |
+----------------------------------+
|word number <0...9> print as words|
+----------------------------------+

+-------------------------+
|\2. Alphabet             |
+=========================+
|arch brov char delta echo|
+-------------------------+
|foxy goof hotel india    |
+-------------------------+
|julia kilo lima mike     |
+-------------------------+
|novakeen oscar prime     |
+-------------------------+
|quebec romeo sierra      |
+-------------------------+
|tango uniform victor     |
+-------------------------+
|whiskey x-ray yankee zulu|
+-------------------------+

.. [e] Prefix 'long' to get spaces on either side.

My example doesn't render very pretty but that can be changed later through customizations. The title is off-center because the screenshot zoomed in

An awesome rst cheatsheet which has a lot of cool examples with how they render. So that should give us the flexibility we need. This should set you up for success working through the Caster Quick Reference.

[sovoid]

@LexiconCode thank you so much for the example. Planning to sit through and work out the remaining doc this weekend. I'll update this PR accordingly

[LexiconCode]

@und3fined-v01d Are you still working towards implementing this or should I close the pr?