Usage docs #68
Merged
Usage docs #68
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
Markdown doesn't support tables of contents which are very nice to have when trying to navigate large numbers of command line options. Asciidoc is similar in complexity to Markdown although less well known.
The detailed usage is not intended to be an entry usage page so keep the name as detailed usage to align with the name from the wiki.
|
Thanks Brett! |
|
Thanks for merging. Unfortunately I appear to have broken the detailed usage table of contents in my last commit. I've raised a new (fairly trivial) PR #69 to fix it. |
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.
Background
With Michal breathing some life into the Osmosis project again it's great to see the recent PR activity.
In my years maintaining the project, there were a number of things that made reviewing and incorporating PRs tedious from my side. I made many little changes over time to make this easier, not least of which were the docker-based build/tests and Travis CI to allow anybody to verify their changes.
But one area that was always a pain was keeping the documentation up to date. Contributors were hesitant to make changes to the wiki until changes were approved and I often found it easier to make the changes myself than to chase people. A number of the current pending PRs will require documentation changes.
I think it would be easier to maintain if the docs were maintained alongside the code itself in Git. Putting the docs on the OSM wiki made sense at the time, but times and tooling have changed.
Change
I have done an automatic conversion of the Mediawiki markup to Asciidoc
I initially tried Markdown but the lack of support for auto-generating a table of contents makes it far from ideal. Asciidoc syntax does support a table of contents.
The doc is currently one huge file (same as the wiki page) but I think it's easier to quickly find what you're looking for that way. It can be split into multiple files if necessary (I'd suggest one per module/plugin).
I've also done some relatively minor cleanups to the main README, the main one being moving the Development docs into a separate file.