As it stands, Section 13.6 (Package Documentation) is an abrupt (and lengthy) departure from the rest of the Packaging chapter, which focuses more on the nuts of bolts of Python packaging.
This can improved by handing each section as follows:
13.6: The opening section introduces the differences between novices, competent practitioners and experts as well as other documentation concepts like a chorus of explanations. None of this information is used in the simple zipf package documentation page that we create throughout the chapter, so we can move this content to an appendix and refer readers to it (i.e. we create a basic ReadTheDocs page during the chapter and then tell people to read the appendix to find out how to add more complete / comprehensive documentation to that page).
13.6.1 Writing good docstrings: This belongs back in Section 4.3, where we first meet and use docstrings.
13.6.2 to 13.6.4: These are the sections where we use sphinx and ReadTheDocs to create the documentation webpage. They can stay in the packaging chapter as they are.
13.6.5 FAQs: We don't actually add any FAQs to our simple documentation webpage, so this section can be put with the opening section in an appendix.
Assuming we create this new appendix with more detailed information about writing documentation, one of the exercises in the packaging chapter could be to read that appendix and add more detailed information to the skeleton sphinx docs we create during the chapter.
There's been some discussion about whether a new appendix or new section is most appropriate.
As it stands, Section 13.6 (Package Documentation) is an abrupt (and lengthy) departure from the rest of the Packaging chapter, which focuses more on the nuts of bolts of Python packaging.
This can improved by handing each section as follows:
Assuming we create this new appendix with more detailed information about writing documentation, one of the exercises in the packaging chapter could be to read that appendix and add more detailed information to the skeleton sphinx docs we create during the chapter.
There's been some discussion about whether a new appendix or new section is most appropriate.