Add documentation on documenting a package. #266
Conversation
|
If we're going to document documentation processes, we should probably also add the relevant bits to the "sample project". When I initially tried to do this, I got pushback that there wasn't an agreed standard approach. If we are now able to document this as the recommended approach, then the sample project should follow it. I'm +1 on doing this. Same applies for test suites, BTW, if anyone ever wants to document recommended testing practices. |
|
I like @jaraco's proposed addition, but when it comes to the suggestion to expand the example project to match, I'll note that when I tried to use a cookiecutter template that included both docs and CI skeletons to start a side project, I found it overwhelming and ended up abandoning the repo (I don't even remember what that project was now, just the feeling of encountering the intimidating number of reminders of "Hey, you're making a big future time commitment here" in the skeleton and the subsequent decision to abandon the idea). I would have been much better off starting with the more minimalist PyPA sample project, focusing on the idea I actually wanted to play with, and only adding other things as they became relevant (if they ever did). Accordingly, I'd strongly encourage keeping the number of things we tell new software publishers they need to provide to the bare minimum - a README that serves as both basic docs and developer guide, and the necessary machinery to actually build the software, publish it to PyPI and check that it works as expected prior to publication. Given that perspective, I'd suggest framing the introduction to the new section as something more along the lines of "While a simple README file that provides both end user and developer documentation is a good starting point for a new project, as a project matures, it frequently becomes desirable to provide more structured user facing documentation." |
|
I am +1 on documenting the recommendation to use RTD when your needs grow beyond a simple I'm not sure the step-by-step guide for publishing to pythonhosted.org is needed, we're trying to move folks away from that so telling new people how to do it seems counterproductive and existing projects already know how to do it. |
|
Part of the reason I wanted to document pythonhosted.org was because I wanted to capture the simplicity and elegance of that approach (mainly that everything could be contained in the repo with 0 additional commands or steps required). I would expect this section to be removed once the recommended approach reached a similar level of simplicity and functionality. As it stands, I'm not aware of any place I can reference that indicates what the old process was. Additionally, having this section helps provide context for the "porting" section. |
|
On the README file matter, I opened an issue about dealing with README files, #210. I think having this Sphinx/RtD coverage is a good idea. It'll serve nicely as a follow on to the README stuff, when I get around to wrapping up the draft I've started (I got a little sidetracked—I'll move it up my to do list, know that there's more interest in that sort of thing). My only comment on the text here is that I'm a little uncomfortable with the word "simple" (as in "simple README" and "simple invocation"). It reads as minimizing the effort required to maintain a package, especially for someone's first time out. I'd hope that the reader would start to feel that it was simple after reading this, but this section might be better served by a show-don't-tell approach. |
|
docception |
|
|
||
| # setup.cfg | ||
| [aliases] | ||
| release = sdist sphinx_build upload upload-docs |
There was a problem hiding this comment.
build_sphinx is the actual command name, is this a typo?
| including it in the ``setup_requires`` of the setup script:: | ||
|
|
||
| # setup.py | ||
| needs_sphinx = {'release', 'sphinx_build'}.intersection(sys.argv) |
There was a problem hiding this comment.
You're right. Thanks for correcting this - it's fixed in a subsequent commit.
|
by the way, i am of the opinion that the current documentatin is great! it's fine to have two approaches provided as well, i don't see why we need to absolutely enforce RTD over pythonshoted.org. recommending it is fine, but we should provide usage for people that have needs that are not fulfulled by RTD or that dislike it for some reason. |
| Layout | ||
| ====== | ||
|
|
||
| Author your documentation as ReStructuredText in ./docs. |
There was a problem hiding this comment.
The Docutils project asks that the word be spelled “reStructuredText”.
| ========== | ||
|
|
||
| The PyPA recommends that the project maintainers publish through | ||
| `Read The Docs <https://readthedocs.org>`_ (RTD). RTD requires |
There was a problem hiding this comment.
RTD also requires that a new account, over and above the necessary PyPI account, is created and maintained with a different organisation.
This document should present tangible options for those who don't want a Read the Docs account, but do want documentation hosted for their PyPI package.
There was a problem hiding this comment.
I think we want to avoid adding a bunch of different options for people, RTD is the right answer for most people and if you're someone with specialized desires you're probably technically sufficient enough to know how to host some static files somewhere.
| will upload the source dist and publish the documentation for the | ||
| project. | ||
|
|
||
| This technique had some advantages that the RTD process does not:: |
There was a problem hiding this comment.
Advantages not yet listed here include:
- Advertising was not displayed.
- The same PyPI account was used to upload the distribution's program and its documentation.
- improving the clarity on file structure - avoiding the possibility of user deviating from parent directory.
This new section attempts to capture my best understanding of the best practices for documenting a project. I welcome feedback and am happy to iterate it or for others to do so.