-
-
Notifications
You must be signed in to change notification settings - Fork 609
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
Add initial Sphinx docs skeleton #1429
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don't move README. It must remain in the project root.
okay |
Hey @jezdez, could you please enable RTD and PR builds for this repo? |
Squash commit messages and add .gitinore in the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do not move README.rst
under docs/
. Change it back.
|
||
project = "pip-tools" | ||
author = "Jazzband Contributors" | ||
copyright = f"2021, {author}" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@jezdez do we have any policy on the copyright format? Technically this should be the year of creation (2012?). But then, some communities remove it altogether because it's not a well-maintained number.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No Jazzband specific policy, but the first year of creation is sensible to indicate when the project was started. It shouldn't be "Jazzband Contributors" but "pip-tools contributors" as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, okay. According to my prior research, the copyright year of the content creation should be stated and then, the years of the updates to the content (list or range). Using the current year (and updating it every January) is incorrect because this reflects the invalid info.
OTOH my understanding is that the copyright notice by itself doesn't have any legal power — it's mostly informational and the copyright is assigned to the (parts) of the content regardless of what that string says.
But because many people interpret it differently, such a statement tends to be incorrect and/or out-of-date. This is why the recent recommendations that I saw were not to use it at all (for the ease of maintenance). I think somebody from RH legal noticed this approach and also the Linux Foundation recommends it: https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/.
P.S. Of course, IANAL so takes this with a grain of salt. Still, I do like the recommendation not to state the year in the copyright lines.
As for "community contributors" vs "project contributors", I saw both. But I don't have a problem with just accepting what you prefer. Just wanted to put this comment in the public, for future reference.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, okay. According to my prior research, the copyright year of the content creation should be stated and then, the years of the updates to the content (list or range). Using the current year (and updating it every January) is incorrect because this reflects the invalid info.
OTOH my understanding is that the copyright notice by itself doesn't have any legal power — it's mostly informational and the copyright is assigned to the (parts) of the content regardless of what that string says.
But because many people interpret it differently, such a statement tends to be incorrect and/or out-of-date. This is why the recent recommendations that I saw were not to use it at all (for the ease of maintenance). I think somebody from RH legal noticed this approach and also the Linux Foundation recommends it: https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/.
P.S. Of course, IANAL so takes this with a grain of salt. Still, I do like the recommendation not to state the year in the copyright lines.
Sure that works for me, let's skip the year number, the changelog provides ample reference to the updates anyway.
As for "community contributors" vs "project contributors", I saw both. But I don't have a problem with just accepting what you prefer. Just wanted to put this comment in the public, for future reference.
I'd prefer to point out that not all community members are automatically contributors to the project. And pip-tools has had contributors before it became a community project. So it's easiest to refer to the contributors as "pip-tools contributors" IMO.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fair enough. This will be addressed via #1467.
Probably, it happened after a not good rebase |
Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
for more information, see https://pre-commit.ci
for more information, see https://pre-commit.ci
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that this is ready for merge, as an initial effort. It's best to add any further improvements in follow-up PRs.
Oh, wow. PR is alive |
Please provide access to the "jazzband-bot" user on Read The Docs. |
Nevermind, saw that you added me personally to the RTD project. |
Yep, was about to add the bot too :) |
The docs build fails because the Sphinx conf file doesn't have a version. I would suggest to use sphinx-quickstart to create a conf.py with all the variables populated. |
Yeah, I saw that too. I guess I overlooked that. It's actually failing because the warnings are turned into errors in the nitpicky mode (although, I don't quite understand why RTD is failing but GHA isn't). I'll look into it and correct what's missing. P.S. I also saw some image-related warnings on RTD too. I wonder if it's some Sphinx ext that is different on RTD and gets populated in that env or it's just flaky... |
FWIW I'm happy that we got this merged at least in this state because it gives up many possibilities to improve things. And maybe even a bunch of easy new-contributor issues could come out of this, which is always good for letting new folks get used to the project setup :) |
if I get you right, after removing "unnecessary lines" and rebasing commits the docs build fails? |
Building HTML doesn't fail ( |
This should fix it: #1466. |
The only doc currently is the project README. It's grown over time and now it may be a good idea to split that information into pieces
I decided to add a simple docs skeleton using
sphinx
Implemented steps:
docs/
dir.docs/
index.rst
to include the current READMEContributor checklist
backwards incompatible
,feature
,enhancement
,deprecation
,bug
,dependency
,docs
orskip-changelog
as they determine changelog listing.Fixes: #1427