Skip to content

Commit 44b4918

Browse files
stevepiercystevepiercy
committed
Tidy up documentation.md
1 parent 53bf1f3 commit 44b4918

File tree

1 file changed

+97
-105
lines changed

1 file changed

+97
-105
lines changed

‎coredev/documentation.md‎

Lines changed: 97 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,110 @@
11
---
22
myst:
33
html_meta:
4-
"description": ""
5-
"property=og:description": ""
6-
"property=og:title": ""
7-
"keywords": ""
4+
"description": "Writing documentation of Plone"
5+
"property=og:description": "Writing documentation of Plone"
6+
"property=og:title": "Writing documentation of Plone"
7+
"keywords": "documentation, Plone"
88
---
99

10-
% -*- coding: utf-8 -*-
11-
1210
# Writing documentation
1311

14-
## Documentation of Plone
12+
For general guidance for contributing documentation, see {doc}`contributing/index`.
13+
14+
For documentation authors, see {doc}`contributing/authors`.
1515

16-
The comprehensive resource for Plone documentation is <http://docs.plone.org/>. The following sections among
17-
others are included:
1816

19-
- {doc}`User Manual </working-with-content/index>`
20-
- {doc}`Installing Plone </manage/installing/index>`
21-
- {doc}`Theme Reference </adapt-and-extend/theming/index>`
22-
- {doc}`Developer Manual </develop/index>`
17+
## Documentation of Plone
18+
19+
The comprehensive resource for Plone documentation is https://6.docs.plone.org/.
20+
The documentation repository is on [GitHub](https://github.com/plone/documentation).
21+
Information for how to contribute to documentation can be found at {doc}`contributing/index`.
2322

24-
The documentation is hosted on [GitHub](https://github.com/plone/documentation) and information how to contribute can be found at {doc}`Contributing to the documentation </about/contributing>`.
2523

2624
## Documenting a package
2725

28-
### The basics
29-
30-
At the very least, your package should include the following forms of documentation:
31-
32-
> {file}`README.rst`
33-
>
34-
> : The readme is the first entry point for most people to your package.
35-
> It will be included on the PyPI page for your egg,
36-
> and on the front page of its GitHub repository.
37-
> It should be formatted using [reStructuredText (reST)](http://docutils.sourceforge.net/rst.html) in order to get formatted properly by those systems.
38-
>
39-
> {file}`README.rst` should include:
40-
>
41-
> - A brief description of the package's purpose
42-
> - Installation information (How do I get it working?)
43-
> - Compatibility information (what versions of Plone does it work with?)
44-
> - Links to other sources of documentation
45-
> - Links to issue trackers, mailing lists, and other ways to get help.
46-
>
47-
> The manual (a.k.a. narrative documentation)
48-
>
49-
> > The manual goes into further depth for people who want to know all about how to use the package.
50-
> >
51-
> > It includes topics like:
52-
> >
53-
> > - What the features are
54-
> > - How to use them (in English—not doctests!)
55-
> > - Information about architecture
56-
> > - Common gotchas
57-
> >
58-
> > The manual should consider various audiences who may need different types of information:
59-
> >
60-
> > - End users who use Plone for content editing but don't manage the site.
61-
> > - Site administrators who install and configure the package.
62-
> > - Integrators who need to extend the functionality of the package in code.
63-
> > - Sysadmins who need to maintain the server running the software.
64-
> >
65-
> > Simple packages with limited functionality can get by with a single page of narrative documentation.
66-
> > In this case it's simplest to include it in an extended {file}`README.rst`.
67-
> > Some excellent examples of a single-page readme are <http://pypi.python.org/pypi/plone.outputfilters> and <https://github.com/plone/plone.app.caching>
68-
> >
69-
> > If your project is moderately complex,
70-
> > you may want to set up your documentation with multiple pages.
71-
> > The best way to do this is to add Sphinx to your project and host your docs on readthedocs.org so that it rebuilds the documentation whenever you push to GitHub.
72-
> > If you do this,
73-
> > your {file}`README.rst` must link off site to the documentation.
74-
>
75-
> Reference (a.k.a. API documentation)
76-
>
77-
> > An API reference provides information about the package's public API (that is, the code that the package exposes for use from external code).
78-
> > It is meant for random access to remind the reader of how a particular class or method works,
79-
> > rather than for reading in its entirety.
80-
> >
81-
> > If the codebase is written with docstrings,
82-
> > API documentation can be automatically generated using Sphinx.
83-
>
84-
> {file}`CHANGES.rst`
85-
>
86-
> : The changelog is a record of all the changes made to the package and who made them,
87-
> with the most recent changes at the top.
88-
> This is maintained separately from the git commit history to give a chance for more user-friendly messages and to and record when releases were made.
89-
>
90-
> A changelog looks something like:
91-
>
92-
> ```
93-
> Changelog
94-
> =========
95-
>
96-
> 1.0 (2012-03-25)
97-
> ----------------
98-
>
99-
> * Documented changelogs.
100-
> [davisagli]
101-
> ```
102-
>
103-
> See <https://raw.github.com/plone/plone.app.caching/master/CHANGES.rst> for a full example.
104-
>
105-
> If a change was related to a bug in the issue tracker,
106-
> the changelog entry should include a link to that issue.
107-
>
108-
> Licenses
109-
>
110-
> : Information about the open source license used for the package should be placed within the {file}`docs` directory.
111-
>
112-
> For Plone core packages, this includes {file}`LICENSE.rst` and {file}`LICENSE.GPL`.
113-
114-
### Using Sphinx
115-
116-
reST References:
117-
: - [Plone documenttion style guide](http://docs.plone.org/about/rst-styleguide.html)
118-
- [Sphinx reST Primer](http://sphinx.pocoo.org/rest.html)
26+
At the very least, your package should include the following forms of documentation.
27+
28+
### `README.md`
29+
30+
The `README.md` is the first entry point for most people to your package.
31+
It will be included on the PyPI page for your package, and on the front page of its GitHub repository.
32+
It should be formatted using [GitHub flavored Markdown](https://github.github.com/gfm/) to get formatted properly by those systems.
33+
34+
`README.md` should include:
35+
36+
- A brief description of the package's purpose.
37+
- Installation information (How do I get it working?)
38+
- Compatibility information (what versions of Plone does it work with?)
39+
- Links to other sources of documentation.
40+
- Links to issue trackers, mailing lists, and other ways to get help.
41+
42+
43+
### The manual (narrative documentation)
44+
45+
The manual goes into further depth for people who want to know all about how to use the package.
46+
47+
It includes topics like:
48+
49+
- What are its features
50+
- How to use them (in English—not doctests!)
51+
- Information about architecture
52+
- Common gotchas
53+
54+
The manual should consider various audiences who may need different types of information:
55+
56+
- End users who use Plone for content editing, but don't manage the site.
57+
- Site administrators who install and configure the package.
58+
- Integrators who need to extend the functionality of the package in code.
59+
- System administrators who need to maintain the server running the software.
60+
61+
Simple packages with limited functionality can get by with a single page of narrative documentation.
62+
In this case, it's simplest to include it in an extended `README.md`.
63+
Some excellent examples of a single-page README are https://pypi.org/project/plone.outputfilters/ and https://github.com/plone/plone.app.caching.
64+
65+
If your project is moderately complex, you may want to set up your documentation with multiple pages.
66+
The preferred way to do this is to add Sphinx to your project, and host your docs on readthedocs.org, so that it rebuilds the documentation whenever you push to GitHub.
67+
If you do this, your `README.md` must link off site to the documentation.
68+
69+
70+
### Reference or API documentation
71+
72+
An API reference provides information about the package's public API (that is, the code that the package exposes for use from external code).
73+
It is meant for random access to remind the reader of how a particular class or method works, rather than for reading in its entirety.
74+
75+
If the codebase is written with docstrings, API documentation can be automatically generated using Sphinx.
76+
77+
78+
### Changes or history
79+
80+
```{todo}
81+
Update for towncrier.
82+
Probably purge all this content.
83+
```
84+
85+
The changelog is a record of all the changes made to the package and who made them, with the most recent changes at the top.
86+
This is maintained separately from the git commit history to give a chance for more user-friendly messages and to and record when releases were made.
87+
88+
A changelog looks something like:
89+
90+
```text
91+
Changelog
92+
=========
93+
94+
1.0 (2012-03-25)
95+
----------------
96+
97+
* Documented changelogs.
98+
[davisagli]
99+
```
100+
101+
See <https://raw.github.com/plone/plone.app.caching/master/CHANGES.rst> for a full example.
102+
103+
If a change was related to a bug in the issue tracker, the changelog entry should include a link to that issue.
104+
105+
106+
### Licenses
107+
108+
Information about the open source license used for the package should be placed within the `docs` directory.
109+
110+
For Plone core packages, this includes `LICENSE.md` and {file}`LICENSE.GPL`.

0 commit comments

Comments
 (0)