Writing ‘guide.rst’¶
Given how much markup you have already learned, you will probably find marking up the Guide to be a more modest challenge than those you have enjoyed so far. Once you have it marked up and looking good, here is a list of bonus challenges you might try out:
- Make all of the references to function, class, and method names turn into real hyperlinks into the API chapter.
- In accomplishing the first goal,
you probably had to use the package name
trianglelib
quite a lot, which involves a quite depressing amount of repetition. While you cannot use themodule::
directive here, since this is not the API documentation, try using the directivecurrentmodule::
trianglelib
at the top of the Guide and verify that you can then remove the module name from the beginning of all of your cross references. - Are the doctests in the guide really running
every time you type
make
doctest
? Try ending the paragraph that precedes them with:
and then with::
and observe the difference in results. - Note the three periods that form an ellipsis
"..."
in the traceback shown in the guide. This is a standard established long ago by the Python Standard Library’s doctest module that lets you avoid including the whole ugly traceback — which you would then have to edit and correct every time a line number changed in one of your source files! Try removing the ellipsis to confirm thatmake
doctest
indeed fails if it is asked to literally match the contents of the traceback. - I have grown to dislike doctests more and more over the years,
most recently because users cannot easily cut-and-paste doctest code
into their own programs without then having to manually backspace
over all of the
>>>
prompts that get pasted in with the code. Convert the example in the Triangle dimensions section into atestcode::
block and atestoutput::
block instead, and confirm that the block is getting detected, executed, and tested when you runmake
doctest
. - If you are able to access the Sphinx documentation
during the tutorial, look up the
math
Sphinx extension and try to figure out how I made the inequality equation so very pretty. As a super bonus, see if you can replace the inequality with this equivalent expression:
\[\begin{split}{a + b \over c} > 1\end{split}\]