Doc: improve Usage section #143
Conversation
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 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
* 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
|
It seems, Travis CI complains about a flake issue that appears in Python 3.4 only. The respective error message (line breaks introduced by me) looks like this: |
|
Should we drop Python 3.4 support in this library for this reason? |
That depends on if you still want to support version 3.4. 😉 If a significant amount of your user base still use it, then it would probably a bad idea. But maybe you should "advertise" it first, for example, in an issue and in the changelog. Funny side note: I've try to check when version 3.4 was released. I even can't select it in https://docs.python.org from the drop-down menu. 😉 If you still want to support version 3.4, you could have replace flake8 with another linter/checker. For example, pystylecode, pylint and probably many others are available. |
|
@tomschr I think problem is somewhere else, from logs it's an import statement: https://travis-ci.org/k-bx/python-semver/jobs/591505916#L301 . In my opinion you can just silence it: Regarding Python 3.4 - I think we should support it as long as it's possible. While I love using new features, probably there is a lot of users who are still using older Python versions (especially 2.7 which will reach EOL status in 3 months: https://pythonclock.org/) |
|
@ppkt Ok Karol, I've added the respective line on the import to silence flake. Let's hope it works. 😉
I fully agree. 👍 |
|
Thanks @tomschr for this other nice PR |
This PR fixes #142. I know, the PR is quite extensive, but it basically boils down to the
usage.rstfile:I also changed the
index.rstfile as I think it can be simplified a bit as well (see commit4d15b25 for the details). Hopefully the comments in the commits make it clear what I did.
I recommend to build the doc with
tox -e docsand to look into the HTML pages.What do you think? 😉