versionchanged:: X.Y” directive (with the same format General improvements or other changes to the APIs that should be emphasized versionadded:: X.Y”, followed by a mandatoryīlank line and an optional description (indented). Our preferred way for marking new features is by prefacing the features’ĭocumentation with: “. Assume documentation readers are using the latest admonition:: Descriptive title rather thanĪll documentation of new features should be written in a way thatĬlearly designates the features that are only available in the Djangoĭevelopment version. code-block:: python, forĮxample, will force highlighting despite invalid syntax. This has the benefit that if the code contains some invalid Prefer relying on automatic highlighting using :: code-block:: to literal blocks so that they get Use intersphinx to reference Python’s and Sphinx’Īdd. This will be run by pre-commit if that is configured. So :mod:`~` willĪll Python code blocks should be formatted using the blacken-docsĪuto-formatter. You can prefix the target with a ~ (that’s a tilde) to get only the This is because Sphinx will generate proper links for the latter, which Hesitate to refer the reader back to the appropriate tutorial rather thanĪdd :mod: `` to your :setting: `INSTALLED_APPS`. Assume that the reader has followed the tutorials and don’t These guides are more advanced than tutorials and assume some knowledge about What matters most in a how-to guide is what a user wants to achieve.Ī how-to should always be result-oriented rather than focused on internalĭetails of how Django implements whatever is being discussed. How-to guides are recipes that take the reader through Yourself explaining basic concepts, you may want to move that material to a Reference guides aren’t the place for general explanation. Reader already understands the basic concepts involved but needs to know or Keep reference material tightly focused on the subject. They describe the functioning of Django’s internal machinery and instruct in Reference guides contain technical references for APIs. Providing background context helps a newcomer connect the topic to things Reluctant to explain things that seem very basic to you - it might be the Link to reference material rather than repeat it. Topic guides aim to explain a concept or subject at a It can be helpful to refer back to what you’ve done and With explanations of how things work - what matters is what the reader does, Understands what we’re trying to achieve. Useful, preferably as early as possible, in order to give them confidence.Įxplain the nature of the problem we’re solving, so that the reader The important thing in a tutorial is to help the reader achieve something Tutorials take the reader by the hand through a series The documentation is organized into several categories:
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |