docs: Various improvements to the contributor guide #14151
Conversation
It's sooooo slow without this.
BGR360
requested review from
ritchie46,
stinodego and
c-peters
as code owners
github-actions
bot
added
documentation
| @@ -228,6 +228,7 @@ From the `py-polars` directory, run `make fmt` to make sure your additions pass | |||
| Polars uses Sphinx to build the API reference. | |||
| This means docstrings in general should follow the [reST](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) format. | |||
| If you want to build the API reference locally, go to the `py-polars/docs` directory and run `make html SPHINXOPTS=-W`. | |||
| By default, this uses only one thread. To speed it up, run `make html SPHINXOPTS="-W -j auto"` to use all available cpus. | |||
There was a problem hiding this comment.
This is enabled by default - see the Makefile.
There was a problem hiding this comment.
I ran without the -j auto and it went extremely slowly for me and only seemed to be using one core. I added -j auto and it went much faster. Is that just because it had been built once before? Is the first time always really slow?
There was a problem hiding this comment.
Looks like the Makefile sets the following by default, as you said:
polars/py-polars/docs/Makefile
Line 8 in f6ba242
However, if you do as the contrib guide suggests and run make html SPHINXOPTS=-W, then you will override that default and get rid of the -j auto. So we should change the guide to say make html.
|
Hi @stinodego. Can we please not close the entire PR and instead negotiate on edits that you'll accept? You only disagreed with a portion of my edits and then basically threw out the rest. That doesn't make me motivated to continue contributing.
Then the guide should omit the message saying "ensure that VSCode is configured to use the virtual environment." That line confused me because it is not clear how to configure that particular thing in VSCode. I had to do an unusual amount of googling to figure it out. Either the guide should more clearly explain what that means or it should omit saying it at all IMO.
Fair. I'm totally fine to remove that section. The problem I was trying to address is that it wasn't immediately clear to me what the Python line length was in this project. I wasn't familiar with 88 as a standard. If this is already covered in another Code Style page, then I agree there's no sense clarifying it here. You made no comment on the Ruff changes I made. |
Again, this is out of scope. The Ruff extension has clear installation instructions, we don't have to copy those.
I can understand that it can come off as harsh when your PR is closed. But please understand we have limited time to manage everything. In this case, you just misjudged what type of content we want as part of the contributing guide. If you open PRs that are not part of an accepted issue, you run the risk of missing the mark. That's OK, there are other things you can work on if you're interested. |
No description provided.