Merge pull request #351 from tomschr/feature/rework-doc

tomschr · web-flow · commit 53f721ab41a0 · 2022-01-23T21:56:25.000+01:00
Introduce new topics for doc
diff --git 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/350.doc.rst b/changelog.d/350.doc.rst
@@ -0,0 +1,2 @@
+Restructure usage section. Create subdirectory "usage/" and splitted
+all section into different files.
diff --git a/changelog.d/351.doc.rst b/changelog.d/351.doc.rst
@@ -0,0 +1,4 @@
+Introduce new topics for:
+
+* "Migration to semver3"
+* "Advanced topics"
diff --git a/docs/advanced/coerce.py b/docs/advanced/coerce.py
diff --git a/docs/advanced/create-subclasses-from-version.rst b/docs/advanced/create-subclasses-from-version.rst
diff --git a/docs/advanced/deal-with-invalid-versions.rst b/docs/advanced/deal-with-invalid-versions.rst
diff --git a/docs/advanced/display-deprecation-warnings.rst b/docs/advanced/display-deprecation-warnings.rst
diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst
@@ -0,0 +1,10 @@
+Advanced topics
+===============
+
+
+
+.. toctree::
+
+    deal-with-invalid-versions
+    create-subclasses-from-version
+    display-deprecation-warnings
diff --git a/docs/advanced/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
@@ -1 +1,3 @@
+.. _change-log:
+
 .. include:: ../CHANGELOG.rst
diff --git 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
@@ -0,0 +1,9 @@
+Migrating to semver3
+====================
+
+
+.. toctree::
+    :maxdepth: 1
+
+    migratetosemver3
+    replace-deprecated-functions.rst
diff --git a/docs/migration/migratetosemver3.rst b/docs/migration/migratetosemver3.rst
@@ -3,15 +3,15 @@
 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
 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/migration/replace-deprecated-functions.rst b/docs/migration/replace-deprecated-functions.rst
diff --git 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
@@ -0,0 +1 @@
+../docs/advanced/coerce.py
diff --git 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
@@ -0,0 +1 @@
+../docs/advanced/semverwithvprefix.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Restructure usage section. Create subdirectory "usage/" and splitted`
	`2`	`+all section into different files.`
Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,8 @@ def parse(cls, version: str) -> "SemVerWithVPrefix":`
`17`	`17`	`"""`
`18`	`18`	`if not version[0] in ("v", "V"):`
`19`	`19`	`raise ValueError(`
`20`		`- "{v!r}: not a valid semantic version tag. Must start with 'v' or 'V'".format(`
	`20`	`+ "{v!r}: not a valid semantic version tag. "`
	`21`	`+ "Must start with 'v' or 'V'".format(`
`21`	`22`	`v=version`
`22`	`23`	`)`
`23`	`24`	`)`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,3 @@`
	`1`	`+.. _change-log:`
	`2`	`+`
`1`	`3`	`.. include:: ../CHANGELOG.rst`