Add guidance on handling comments in languages with significant indentation

[nchammas]

• Expand the indented tree example to show how to correctly handle comments.
• Add a new section to Recipes that references this example, as it's perhaps the most accessible starting point for those looking to write a grammar with significant indentation.
• Add some guidances on how to build the docs.
• Fix a warning coming from Sphinx by configuring the language explicitly.

Related to (though perhaps not exactly a fix for) #863.

[nchammas]

I added some instructions on how to build the docs and, since I am now able to review the built docs, I also fixed the markup.

[nchammas]

Dunno if this shows up for you too after running make html, but I assume it's meant to be ignored.

[erezsh]

I don't think I get this. Not sure why you are.

[nchammas]

Could it be the version of Sphinx you are running? This is what I have:

$ pip list | grep -i sphinx
Sphinx                        7.3.7
sphinx-gallery                0.18.0
sphinx-markdown-tables        0.0.17
sphinx-rtd-theme              3.0.2
sphinxcontrib-applehelp       2.0.0
sphinxcontrib-devhelp         2.0.0
sphinxcontrib-htmlhelp        2.1.0
sphinxcontrib-jquery          4.1
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          2.0.0
sphinxcontrib-serializinghtml 2.0.0

[nchammas]

The dev requirements are open ended, so if you haven't updated them in a while you are likely running a much older version of Sphinx than I am (since I just installed them today).

If you're courageous, I would try pip install -U -r docs/requirements.txt and then see if you get the same behavior that I am seeing.

[erezsh]

Yes, you're right, it gets generated by sphinx-gallery. I think it's fine to just ignore it.

[erezsh]

Thanks!