Migrate tox 3 documentation #2408
Conversation
jugmac00
left a comment
jugmac00
left a comment
There was a problem hiding this comment.
Thanks a lot!
I had a first pass - mostly from the GitHub ui, and only occasionally on the rendered docs - I will have another one when the PR is finished.
Apart from my inline comments, you certainly noticed that building the documentation is currently broken to an changed anchor in the pytest documentation.
Speaking of the pytest documentation, have you noticed that they restructured their documentation to follow https://diataxis.fr/ documentation framework? (not a technical framework, but a way to structure your docs).
Our documentation looks good, but maybe you have a time to have a look at diataxis whether you like it.
e.g. our faq is not really a faq as I have not seen too many people asking for customizing virtualenv creation - currently our faq is more like a place to put stuff which does not fit anywhere else.
In diataxis these would be all "how-tos". Our user-guide would be a tutorial, configuration, tox cli interface and API would go in a reference section, and so on...
If we ever would plan to restructure the documentation now would be a great time.
Oh - and I think we need a What's new in tox version4 page - with all highlights.
| Name of the Python dependencies as specified by `PEP-440`_. Installed into the environment prior to project after | ||
| environment creation, but before package installation. All installer commands are executed using the :ref:`tox_root` | ||
| as the current working directory. | ||
| Name of the Python dependencies. Installed into the environment prior to project after environment creation, but |
There was a problem hiding this comment.
Installed into the environment prior to project after environment creation
I do not understand this sentence. Maybe "after" should be removed? Or even "project after" should be removed?
We should rephrase this sentence.
Or does it mean...
"Installed into the environment prior to project creation, after environment creation,"
If so.. I'd prefer some repetition (the word creation) to make the sentence more clear.
| Here we use an environment substitution to set the index URL if not set by the user, but otherwise default to our target | ||
| URI. |
There was a problem hiding this comment.
This sounds a bit complicated... maybe something like: "We define a default index URL, but user can override the value" .. something like that...
| requires = ["hatchling>=0.22", "hatch-vcs>=0.2"] | ||
| By default tox will create and install a source distribution. You can configure to build a wheel instead by setting | ||
| the :ref:`package` configuration to ``wheel``. Wheels are much faster to install than source distributions. |
There was a problem hiding this comment.
This ref might not be correct. When following, I do not see how to set package to wheel.
Ah, ok... it goes to the wrong #package anchor.
| Advanced features | ||
| ----------------- | ||
|
|
||
| tox supports these features that 90 percent of the time you'll not need, but are very useful the other ten percent. |
There was a problem hiding this comment.
I think this line does not add any value to our documentation.
|
It looks like cpython is also adopting the Diátaxis framework for documentation: https://diataxis.fr/how-to-use-diataxis/ I think it would be a great idea to also adopt it. |
|
I'm not against it, but until we have availability for someone (mostly me in the first phase) to work on it, it doesn't really matter 😆 |
gaborbernat
force-pushed
the
rewrite
branch
from
5bd1c53 to
252299c
Compare
|
One thing I've learned part of the diatrixis framework is to not do big bang release. Considering that we'll merge this as is and do smaller follow-up PRs to make it diatrixis. |
This is the first pass. Signed-off-by: Bernát Gábor <[email protected]>
Co-authored-by: Jürgen Gmach <[email protected]>
Co-authored-by: Jürgen Gmach <[email protected]>
Co-authored-by: Jürgen Gmach <[email protected]>
Co-authored-by: Jürgen Gmach <[email protected]>
Co-authored-by: Jürgen Gmach <[email protected]> Signed-off-by: Bernát Gábor <[email protected]>
3 participants
This is the first pass.
Signed-off-by: Bernát Gábor [email protected]