Skip to content

Doc: Improve Usage Section #142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
tomschr opened this issue Sep 30, 2019 · 0 comments · Fixed by #143
Closed

Doc: Improve Usage Section #142

tomschr opened this issue Sep 30, 2019 · 0 comments · Fixed by #143

Comments

@tomschr
Copy link
Member

tomschr commented Sep 30, 2019

Situation

Currently, the documentation in the "Usage" section is limited. It covers the important parts very briefly, but also lacks other features that are added recently, For example, iterating over a VersionInfo or passing strings to VersionInfo and others.

IMHO, the documentation is an integral and crucial part of helping our users to use the module successfully and efficiently.

Proposed Solution

The "Usage" section should cover, as an example, but not limited to:

  • create instances of VersionInfo
  • access different parts of a version
  • convert different types into each other (for example, a dict into VersionInfo and vice versa)
  • increase/bump parts of a version
  • compare two versions
tomschr added a commit to tomschr/python-semver that referenced this issue Sep 30, 2019
* Use descriptive titles (verb+ing) to better find the topic
* Structure the content with (sub)sections
* Try to structure the different sections with list if there
  are different options to make it more readable
* Document other, possible unknown features
s-celles pushed a commit that referenced this issue Oct 1, 2019
* Change titles to using verb instead of noun

* Adding version information in docs/conf.py

Currently, the version of semver is imported (using
from semver import __version__).

To avoid importing semver, version string could be managed
through bumpversion2. However, this is out of scope for
this PR.

* Improve entry page

* Improve main title with semver's version and a catchy phrase
* Move the |latest-version| placeholder to the other placeholders
  like build status, downloads etc.
* Remove the "Welcome bla" heading as it introduces a lonly section
  and it is mostly useless
* Add a short explanation about the "version style" major.minor.patch
  (cited from semver.org)
* Reference the other parts with just the filename (with the .rst extension)
  and without the title. The title is automatically retrieved from
  the file, no need to repeat it. This makes the overall doc more consistent.
* Change py.test -> pytest

* Fix #142: Improve usage documentation

* Use descriptive titles (verb+ing) to better find the topic
* Structure the content with (sub)sections
* Try to structure the different sections with list if there
  are different options to make it more readable
* Document other, possible unknown features

* Silence flake8 with "noqa: E402"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant