Burst run's documentation between user guide and dev guide, merge FAQ's run questions in the user guide #6658
Conversation
Pierre-Sassoulas
force-pushed
the
burst-run-between-user-guide-and-dev-guide
branch
from
77735a4 to
ac2713a
Compare
Pull Request Test Coverage Report for Build 2365750878
💛 - Coveralls |
doc/development_guide/run.rst
Outdated
| @@ -0,0 +1,83 @@ | |||
| =========================================== | |||
There was a problem hiding this comment.
Let's call this file run_as_package or something like that. run.html feels like we might want to use it for some more general pages in the future.
doc/development_guide/run.rst
Outdated
|
|
||
| .. sourcecode:: python | ||
|
|
||
| from pylint import epylint as lint |
There was a problem hiding this comment.
This example should be updated as epylint is not the same as pylint. We shouldn't suggest them interchangeably.
doc/development_guide/run.rst
Outdated
|
|
||
| .. sourcecode:: python | ||
|
|
||
| from pylint import epylint as lint |
Co-authored-by: Daniël van Noord <[email protected]>
|
I made a somewhat big change by renaming "run" to "API" for the dev guide. |
| @@ -0,0 +1,22 @@ | |||
| ======= | |||
| epylint | |||
There was a problem hiding this comment.
This whole section of API should probably go into User guide? It's more usage related than development related right?
There was a problem hiding this comment.
For me everything that is not doable by using the pylint executable with options is development. (Beside creating a file to call epylint's API is development ?).
There was a problem hiding this comment.
But Development is about developing pylint right? Since pylint is a developer's tool everything related to it will be "development", but I feel like this is more part of "using pylint" than "developing or contributing to pylint". We never use these APIs in our own development and you don't really need them when writing a checker.
There was a problem hiding this comment.
Right, it's still unclear what is what. How about this:
- User guides : using pylint's result from the command line
- Developer guides: using pylint's API programmatically, understanding pylint plugin system, extension, checkers, etc.
- Contributor guides : developing for pylint itself launching tests, process, etc. (also maintaining pylint : we have a release.md document that is not included in the doc yet).
There was a problem hiding this comment.
I like that! Although I would perhaps put Developers and Contributing under a more general header of "Development" like black does. That would also allow showing some of the sub-headers of Usage in the sidebar.
There was a problem hiding this comment.
I think we're almost ready to do the big table of content revamp then 😄 .
There was a problem hiding this comment.
I'm planning on adding readme and release.md first.
There was a problem hiding this comment.
I'll let you choose, but I'd prefer a PR that sets up the TOC first. It's quite hard to review content + redirects + new pages at the same time.
If we create one PR with all pages/sections we want to have and make sure redirects work we can then do the content afterwards. I would even be okay with adding some blank pages for now considering that you're working on this quite hard at the moment.
| ### | ||
| API | ||
| ### | ||
|
|
There was a problem hiding this comment.
We should probably write something here. https://pylint--6658.org.readthedocs.build/en/6658/development_guide/api/index.html feels a bit empty.
doc/development_guide/api/pylint.rst
Outdated
| As you would launch the command line | ||
| ------------------------------------ | ||
|
|
||
| You can use the ``run_pylint`` function, which is the same function | ||
| called by the command line. You can either patch ``sys.argv``: | ||
|
|
||
| .. sourcecode:: python | ||
|
|
||
| from pylint import run_pylint | ||
|
|
||
| sys.argv = ["pylint", "--disable=line-too-long", "myfile.py"] | ||
| run_pylint() | ||
|
|
||
|
|
||
| Or supply arguments yourself: | ||
|
|
||
| .. sourcecode:: python | ||
|
|
||
| from pylint import run_pylint | ||
|
|
||
| run_pylint(argv=["--disable=line-too-long", "myfile.py"]) |
There was a problem hiding this comment.
Considering:
| As you would launch the command line | |
| ------------------------------------ | |
| You can use the ``run_pylint`` function, which is the same function | |
| called by the command line. You can either patch ``sys.argv``: | |
| .. sourcecode:: python | |
| from pylint import run_pylint | |
| sys.argv = ["pylint", "--disable=line-too-long", "myfile.py"] | |
| run_pylint() | |
| Or supply arguments yourself: | |
| .. sourcecode:: python | |
| from pylint import run_pylint | |
| run_pylint(argv=["--disable=line-too-long", "myfile.py"]) | |
| As you would launch the command line | |
| ------------------------------------ | |
| You can use the ``run_pylint`` function, which is the same function | |
| called by the command line. | |
| .. sourcecode:: python | |
| from pylint import run_pylint | |
| run_pylint(argv=["--disable=line-too-long", "myfile.py"]) |
There should be one obvious way to do it
There was a problem hiding this comment.
Yeah I like the suggestion better although I would keep Or supply arguments yourself: at the end.
There was a problem hiding this comment.
e87b2ce ? Not sure if it is what you meant :)
Type of Changes
Description
Reviewable cleanup before #6589