From 68553feff8e886250c40df12a2af45daea40c138 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Sun, 23 Jan 2022 20:26:56 +0100 Subject: [PATCH 1/2] Add missing changelog file for #350 --- changelog.d/350.doc.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 changelog.d/350.doc.rst diff --git a/changelog.d/350.doc.rst b/changelog.d/350.doc.rst new file mode 100644 index 00000000..2fa92f0a --- /dev/null +++ b/changelog.d/350.doc.rst @@ -0,0 +1,2 @@ +Restructure usage section. Create subdirectory "usage/" and splitted +all section into different files. From 838527bf6bb34d3ed2ecbb2bc8b418af3012e44d Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Sun, 23 Jan 2022 16:53:40 +0100 Subject: [PATCH 2/2] Introduce new topics for doc * Move some files that better fit into an "Advanced topic" * Introduce "Migration to semver3" topic --- CONTRIBUTING.rst | 4 ++-- changelog.d/351.doc.rst | 4 ++++ docs/{usage => advanced}/coerce.py | 0 .../create-subclasses-from-version.rst | 0 .../{usage => advanced}/deal-with-invalid-versions.rst | 0 .../display-deprecation-warnings.rst | 0 docs/advanced/index.rst | 10 ++++++++++ docs/{usage => advanced}/semverwithvprefix.py | 3 ++- docs/changelog.rst | 2 ++ docs/index.rst | 4 +++- docs/migration/index.rst | 9 +++++++++ docs/{ => migration}/migratetosemver3.rst | 4 ++-- .../replace-deprecated-functions.rst | 0 docs/usage/index.rst | 4 ---- tests/coerce.py | 1 + tests/conftest.py | 2 +- tests/semverwithvprefix.py | 1 + 17 files changed, 37 insertions(+), 11 deletions(-) create mode 100644 changelog.d/351.doc.rst rename docs/{usage => advanced}/coerce.py (100%) rename docs/{usage => advanced}/create-subclasses-from-version.rst (100%) rename docs/{usage => advanced}/deal-with-invalid-versions.rst (100%) rename docs/{usage => advanced}/display-deprecation-warnings.rst (100%) create mode 100644 docs/advanced/index.rst rename docs/{usage => advanced}/semverwithvprefix.py (86%) create mode 100644 docs/migration/index.rst rename docs/{ => migration}/migratetosemver3.rst (93%) rename docs/{usage => migration}/replace-deprecated-functions.rst (100%) create mode 120000 tests/coerce.py create mode 120000 tests/semverwithvprefix.py diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 5fd75ab2..e0210cc9 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -64,7 +64,7 @@ We recommend the following workflow: a. Write test cases and run the complete test suite, see :ref:`testsuite` for details. - b. Write a changelog entry, see section :ref:`changelog`. + b. Write a changelog entry, see section :ref:`add-changelog`. c. If you have implemented a new feature, document it into our documentation to help our reader. See section :ref:`doc` for @@ -214,7 +214,7 @@ documentation includes: edge cases. -.. _changelog: +.. _add-changelog: Adding a Changelog Entry ------------------------ diff --git a/changelog.d/351.doc.rst b/changelog.d/351.doc.rst new file mode 100644 index 00000000..0b5199fa --- /dev/null +++ b/changelog.d/351.doc.rst @@ -0,0 +1,4 @@ +Introduce new topics for: + +* "Migration to semver3" +* "Advanced topics" diff --git a/docs/usage/coerce.py b/docs/advanced/coerce.py similarity index 100% rename from docs/usage/coerce.py rename to docs/advanced/coerce.py diff --git a/docs/usage/create-subclasses-from-version.rst b/docs/advanced/create-subclasses-from-version.rst similarity index 100% rename from docs/usage/create-subclasses-from-version.rst rename to docs/advanced/create-subclasses-from-version.rst diff --git a/docs/usage/deal-with-invalid-versions.rst b/docs/advanced/deal-with-invalid-versions.rst similarity index 100% rename from docs/usage/deal-with-invalid-versions.rst rename to docs/advanced/deal-with-invalid-versions.rst diff --git a/docs/usage/display-deprecation-warnings.rst b/docs/advanced/display-deprecation-warnings.rst similarity index 100% rename from docs/usage/display-deprecation-warnings.rst rename to docs/advanced/display-deprecation-warnings.rst diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst new file mode 100644 index 00000000..de7da166 --- /dev/null +++ b/docs/advanced/index.rst @@ -0,0 +1,10 @@ +Advanced topics +=============== + + + +.. toctree:: + + deal-with-invalid-versions + create-subclasses-from-version + display-deprecation-warnings \ No newline at end of file diff --git a/docs/usage/semverwithvprefix.py b/docs/advanced/semverwithvprefix.py similarity index 86% rename from docs/usage/semverwithvprefix.py rename to docs/advanced/semverwithvprefix.py index 5e375031..4395a95e 100644 --- a/docs/usage/semverwithvprefix.py +++ b/docs/advanced/semverwithvprefix.py @@ -17,7 +17,8 @@ def parse(cls, version: str) -> "SemVerWithVPrefix": """ if not version[0] in ("v", "V"): raise ValueError( - "{v!r}: not a valid semantic version tag. Must start with 'v' or 'V'".format( + "{v!r}: not a valid semantic version tag. " + "Must start with 'v' or 'V'".format( v=version ) ) diff --git a/docs/changelog.rst b/docs/changelog.rst index 565b0521..e1e273b4 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1 +1,3 @@ +.. _change-log: + .. include:: ../CHANGELOG.rst diff --git a/docs/index.rst b/docs/index.rst index 3e2771a0..deac1cd0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,7 +11,8 @@ Semver |version| -- Semantic Versioning install usage/index - migratetosemver3 + migration/index + advanced/index development api @@ -31,6 +32,7 @@ Semver |version| -- Semantic Versioning changelog changelog-semver2 + Indices and Tables ================== diff --git a/docs/migration/index.rst b/docs/migration/index.rst new file mode 100644 index 00000000..c6af7c05 --- /dev/null +++ b/docs/migration/index.rst @@ -0,0 +1,9 @@ +Migrating to semver3 +==================== + + +.. toctree:: + :maxdepth: 1 + + migratetosemver3 + replace-deprecated-functions.rst diff --git a/docs/migratetosemver3.rst b/docs/migration/migratetosemver3.rst similarity index 93% rename from docs/migratetosemver3.rst rename to docs/migration/migratetosemver3.rst index d977bc03..f869cad3 100644 --- a/docs/migratetosemver3.rst +++ b/docs/migration/migratetosemver3.rst @@ -3,7 +3,7 @@ Migrating from semver2 to semver3 ================================= -This chapter describes the visible differences for +This document describes the visible differences for users and how your code stays compatible for semver3. Although the development team tries to make the transition @@ -11,7 +11,7 @@ to semver3 as smooth as possible, at some point change is inevitable. For a more detailed overview of all the changes, refer -to our :ref:`changelog`. +to our :ref:`change-log`. Use Version instead of VersionInfo diff --git a/docs/usage/replace-deprecated-functions.rst b/docs/migration/replace-deprecated-functions.rst similarity index 100% rename from docs/usage/replace-deprecated-functions.rst rename to docs/migration/replace-deprecated-functions.rst diff --git a/docs/usage/index.rst b/docs/usage/index.rst index b843809c..ddfc2284 100644 --- a/docs/usage/index.rst +++ b/docs/usage/index.rst @@ -18,7 +18,3 @@ Using semver determine-version-equality compare-versions-through-expression get-min-and-max-of-multiple-versions - deal-with-invalid-versions - replace-deprecated-functions - display-deprecation-warnings - create-subclasses-from-version diff --git a/tests/coerce.py b/tests/coerce.py new file mode 120000 index 00000000..e79106a2 --- /dev/null +++ b/tests/coerce.py @@ -0,0 +1 @@ +../docs/advanced/coerce.py \ No newline at end of file diff --git a/tests/conftest.py b/tests/conftest.py index eb1911d1..40b56ab1 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -4,7 +4,7 @@ import semver -sys.path.insert(0, "docs/usage") +# sys.path.insert(0, "docs/usage") from coerce import coerce # noqa:E402 from semverwithvprefix import SemVerWithVPrefix # noqa:E402 diff --git a/tests/semverwithvprefix.py b/tests/semverwithvprefix.py new file mode 120000 index 00000000..d1a8d995 --- /dev/null +++ b/tests/semverwithvprefix.py @@ -0,0 +1 @@ +../docs/advanced/semverwithvprefix.py \ No newline at end of file