Your first assignment is to create your own
whose output looks just like the chapter
“The trianglelib API reference” at the end of this handout!
Approach this task as three smaller steps.
For your first try, just use three plain autodoc directives
to generate your entire chapter from the contents
Separate the three
with sub-titles to make the chapter more organized:
The trianglelib API reference ============================= .. automodule:: triangles :members: The “shape” module ------------------ .. automodule:: triangles.shape :members: The “utils” module ------------------ .. automodule:: triangles.utils :members:
api to the list of chapters in your table of contents
index.rst file, and then build the resulting document.
Note that you will get errors
if Sphinx cannot find the
trianglelib Python module,
in which case you should consult the solutions
in the Notes on Using Sphinx chapter of this document.
Once your build is successful, take a look at your output document. It should already contain most of the information that you need! Compare the output carefully with the corresponding example bound with this documentation. What changes will you have to learn how to make in order to get the two documents to match?
where is the text describing how to instantiate
You will need to add it manually,
autodoc does not pull that information from your code.
So you will need to take control of that class’s presentation.
To take control,
shape from the using the
to using the plain old
which produces no output of its own
but makes you explicitly provide its contents yourself.
This frees you up to build your own version of
that includes some introductory text before getting to work
on its members:
.. module:: triangles.shape .. autoclass:: Triangle :members: <Describe instantiation here!>
Note that the name of the class
does not have to be prefixed with
had already told Sphinx about where to look
for the classes and methods that you describe in this file.
You are getting closer,
but the documentation still does not look exactly the same.
For one thing, the first method shown right now is
since functions and attributes
are shown in alphabetical order by default.
Try each of the following directives in turn
to achieve some other possible orderings:
:autodoc_member_order: bysource :autodoc_member_order: groupwise :members: is_equilateral, is_isosceles, ...
Note that you can also say
followed by the names of methods to leave out.
At that point your API chapter will begin to strongly resemble the printed one! Here are further bonus goals in case you finish early:
- How can you display the attributes
cas presented in the printed document?
- The printed chapter describes the triangle
__eq__()method by actually showing two triangles compared with the
==operator; can you get your version of the document to show the same thing?
- If you have not done so already, add in the example doctest that stands just beneath the instantiation instructions in the printed version of the chapter.
- Try running
doctests— are your code samples correct? Add some deliberate errors into the code to see what the output looks like when doctests fail.
- Create example doctests for a few of the functions in
utilsby turning off
utilsmodule, explicitly autodoc’ing each of its five functions to pull them back into your documentation, and adding example code beneath each one.