Update Compiling.rst

[ben-albrecht]

In response to Brad's comment, I made some changes to compiling.rst and other bits of documentation.

To summarize:

• Put man page under the 'Compiling Chapel Programs' section
• Renamed it Chapel Man Page
  • Can't get inline code formatting in the sidebar, and the lower case 'chpl man page' among all other capitalized titles looks off.
• Cross linked the man page from compiling.rst
• (Bonus point) Fixed the table formatting in compiling.rst

In the process of making these changes, I noticed that our Sphinx project is broken with that latest version of Sphinx (1.3.5), due to a change that throws a warning when Pygments throws an ErrorToken.

There were a handful of code blocks throughout the documentation that raised this error, so I corrected them to be valid Chapel code, or in some cases, made them .. code-block:: text when they weren't Chapel code to begin with.

[ronawho]

This looks good to me (I took a look to make sure it wouldn't conflict with some doc changes I'm about to make.)

[ben-albrecht]

@bradcray do you still want to take a look at this or can I merge it?

[bradcray]

Thanks for making these changes. The main thing that gives me pause is the changing of the code blocks to text from chapel. In what way does not doing so break the project? (i.e., what would I look at to understand the effects firsthand?)

[ben-albrecht]

If a user or developer had the latest version of Sphinx installed and was not using the virtualenv to build the documentation, they would encounter a warning that is treated like an error. I figure we might as well maintain compatibility with the latest version if it's fairly easy to do.

The affected code blocks actually render no differently with this change, since Pygments was already failing silently for the syntax highlighting anyway.

[bradcray]

I'm still confused about what it is in the code blocks / Pygments / our Pygments highlighter that's causing it to fail. I.e., what should we do to actually address the error rather than work around it? (and can we do that instead of working around it?).

[ben-albrecht]

As discussed (in-person), we'll just modify the code-blocks to be valid Chapel in lieu of modifying pygments to understand our Chapel pseudocode.

I will let @benharsh review the changes to his code-block examples before merging.

[benharsh]

Looks good to me, thanks! 👍

[bradcray]

This looks good to me now too. I must admit, I didn't actually look at the re-chpldoc'd files online, but am assuming they're great. Thanks!