Re-organize the fedmsg documentation #453
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Codecov Report
@@ Coverage Diff @@
## develop #453 +/- ##
========================================
Coverage 57.55% 57.55%
========================================
Files 29 29
Lines 1821 1821
Branches 300 300
========================================
Hits 1048 1048
Misses 685 685
Partials 88 88
Continue to review full report at Codecov.
|
jeremycline
force-pushed
the
reorg-docs
branch
2 times, most recently
from
c84a515 to
931a1dd
Compare
The fedmsg documentation has gather a lot of cruft over the years - there are many files that were not included in the toctree or were no longer relevant. Additionally, the documentation was split up in confusing ways (for example, the STOMP configuration was not in the configuration section). This commit removes documentation that no longer applies and moves as much documentation as possible into the Python doc blocks. It defines a public API. It tries to organize the documentation so that it is easy to find the section you're interested in. Signed-off-by: Jeremy Cline <[email protected]>
bowlofeggs
approved these changes
Jul 24, 2017
| # The suffix(es) of source filenames. | ||
| # You can specify multiple suffix as a list of string: | ||
| # | ||
| source_suffix = ['.rst', '.md'] |
There was a problem hiding this comment.
Whoah I didn't know Sphinx could do markdown. That tempts me to convert my docs to markdown.
| To publish a message, call :func:`fedmsg.publish`. Your message should be a | ||
| Python dictionary capable of being JSON-serialized. Additionally, any strings | ||
| it contains should be a text type. That is, :class:`unicode` in Python 2 and | ||
| :class:`str` in Python 3. |
There was a problem hiding this comment.
It's the other way around (sorta)
~ $ python2
>>> str is bytes
True
>>> str is unicode
False
~ $ python3
>>> str is bytes
False
>>> str is unicode
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'unicode' is not defined
>>>
| @@ -32,13 +32,13 @@ | |||
|
|
|||
|
|
|||
| class RelayCommand(BaseCommand): | |||
| """ Relay connections from active loggers to the bus. | |||
| """Relay connections from active loggers to the bus. | |||
There was a problem hiding this comment.
This change seems fine, but unrelated.
|
|
||
| Tools like ``fedmsg-logger`` require that an instance of ``fedmsg-relay`` be running | ||
| *somewhere* and that it's inbound address be listed in the config as one of the | ||
| entries in :ref:`conf-relay-inbound`. |
There was a problem hiding this comment.
It could be nice to document the type of the return value too.
| """ :mod:`fedmsg.config` handles loading, processing and validation of | ||
| all configuration. | ||
| """ | ||
| This module handles loading, processing and validation of all configuration. |
There was a problem hiding this comment.
Oxford comma saves capitalists money.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR has several goals:
Organize the documentation so what users want to read is easy to find. This has separated the documentation into three sections (User Guide, API Guide, Contributor Guide). Sections have been ordered in what I think are most-used to least-used.
Make the landing page short and to the point.
Remove a lot of the old/outdated documentation
Merge different documentation sections about the same topic.
Remove a lot of the Fedora-specific documentation. This can live in the Fedora infra docs project.
It's an unfortunately large pull request and I'm really sorry for that. For the ease of the reviewers, I've got a readthedocs.org build of this branch: http://jcline-fedmsg.readthedocs.io/en/reorg-docs/. You can compare this to https://fedmsg.readthedocs.io/en/latest/ which is the current documentation.
I don't expect this to pass through review without a lot of revision. Please be generous with your feedback 😃.