Repository: python/mypy
Pull request: Improved config_file.rst writing
Fixes [#7961](https://github.com/python/mypy/issues/7961)

- Moved configuration file precedence order from a sentence into an enumerated list
  - Used the term "precedence order" to be consistent with the wording in section "Config file format"
  - Moved the command-line flag ```--config-file``` as the first in the precedence order
- Condensed information written in the paragraph after the list
- Changed section "Examples" to "Example ```mypy.ini```" to differentiate and be consistent with section "Example ```pyproject.toml```"

<!--
Checklist:
- Read the [Contributing Guidelines](https://github.com/python/mypy/blob/master/CONTRIBUTING.md)
- Add tests for all changed behaviour.
- If you can't add a test, please explain why and how you verified your changes work.
- Make sure CI passes.
- Please do not force push to the PR once it has been reviewed.
-->


Problem statement:
Improve documentation - cannot locate mypy.ini nor setup.cfg files
Trying to get started and I cannot find the config file to inform mypy where the libraries that I'm using are. The documentation is ambiguous as to where the config file is nor does it inform you on how to generate one; there is also no samples of a config file that I could find.

Hints from issue discussion:
Did you read https://mypy.readthedocs.io/en/latest/config_file.html?
Of course I did. What is defined as current directory, mypy's install directory, the active environment, or the current directory I'm calling mypy from? There are other options, why don't stick to one to reduce ambiguity? I like the --config-file command line flag by the way.

The key problem for new to mypy individuals I think is the missing config file example with some libraries is crucial for adoption. Think about your audience; you'd want someone new to get started as soon as possible before they move on to something else or give up.
________________________________
From: Jukka Lehtosalo <notifications@github.com>
Sent: Monday, November 18, 2019 11:55:55 AM
To: python/mypy <mypy@noreply.github.com>
Cc: George J <gjnet@live.com>; Author <author@noreply.github.com>
Subject: Re: [python/mypy] Improve documentation - cannot locate mypy.ini nor setup.cfg files (#7961)


Did you read https://mypy.readthedocs.io/en/latest/config_file.html<https://nam02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmypy.readthedocs.io%2Fen%2Flatest%2Fconfig_file.html&data=02%7C01%7C%7C7a6d0a919544458cd66608d76c1e450e%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637096749566369937&sdata=KvYiSRihNAn2JpeLBXJadZ2dnxSvkSDyedPfiN6ocUo%3D&reserved=0>?

-
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub<https://nam02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fpython%2Fmypy%2Fissues%2F7961%3Femail_source%3Dnotifications%26email_token%3DAFM4L54UUPPO5NHXM2HJZPLQUJ7EXA5CNFSM4JOE3C72YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEEKGIZA%23issuecomment-554984548&data=02%7C01%7C%7C7a6d0a919544458cd66608d76c1e450e%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637096749566379948&sdata=Ek%2FzfKt0KbEZnh%2B7erYoFLPXuiqmySVd4xhDah%2BYZpI%3D&reserved=0>, or unsubscribe<https://nam02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAFM4L5723FOEVPJLMUKLW5TQUJ7EXANCNFSM4JOE3C7Q&data=02%7C01%7C%7C7a6d0a919544458cd66608d76c1e450e%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637096749566389953&sdata=dQ0hcKmwt2m0e92iQ9p63eX7op7sZJrd1L%2F1mRd0oAQ%3D&reserved=0>.

Thanks for the feedback -- I agree that the section could be clearer. Would like to suggest a PR that improves the wording? The current directory refers to the current working directory. A more detailed example or examples would also be good to have.
> 
> 
> Thanks for the feedback -- I agree that the section could be clearer. Would like to suggest a PR that improves the wording? The current directory refers to the current working directory. A more detailed example or examples would also be good to have.

Sure, I'd like to contribute! Which branch should I use? If you don't mind, please instruct me on how to do a pull request properly please. 
@JukkaL  I tried my hand in simplifying the wording
Hi everyone, this is my first time contributing to an open source project. Please review my changes and let me know what changes need to be made. Thank you!

Edit: I described the changes made on the pull request.

Commit message: Merge branch 'master' of github.com:williamsantosa/mypy

Patch to review:
diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst
index 3b96e6bd7a5a..bb3b0c2e68c0 100644
--- a/docs/source/config_file.rst
+++ b/docs/source/config_file.rst
@@ -3,17 +3,22 @@
 The mypy configuration file
 ===========================
 
-Mypy supports reading configuration settings from a file.  By default
-it uses the file ``mypy.ini`` with a fallback to ``.mypy.ini``, then ``pyproject.toml``,
-then ``setup.cfg`` in the current directory, then ``$XDG_CONFIG_HOME/mypy/config``, then
-``~/.config/mypy/config``, and finally ``.mypy.ini`` in the user home directory
-if none of them are found; the :option:`--config-file <mypy --config-file>` command-line flag can be used
-to read a different file instead (see :ref:`config-file-flag`).
+Mypy supports reading configuration settings from a file with the following precedence order:
+
+    1. ``./mypy.ini``
+    2. ``./.mypy.ini``
+    3. ``./pyproject.toml``
+    4. ``./setup.cfg``
+    5. ``$XDG_CONFIG_HOME/mypy/config``
+    6. ``~/.config/mypy/config``
+    7. ``~/.mypy.ini``
 
 It is important to understand that there is no merging of configuration
-files, as it would lead to ambiguity.  The :option:`--config-file <mypy --config-file>` flag
-has the highest precedence and must be correct; otherwise mypy will report
-an error and exit.  Without command line option, mypy will look for configuration files in the above mentioned order.
+files, as it would lead to ambiguity. The :option:`--config-file <mypy --config-file>`
+command-line flag (see :ref:`config-file-flag`) has the highest precedence and 
+must be correct; otherwise mypy will report an error and exit. Without the
+command line option, mypy will look for configuration files in the
+precedence order above. 
 
 Most flags correspond closely to :ref:`command-line flags
 <command-line>` but there are some differences in flag names and some
@@ -103,8 +108,8 @@ their name or by (when applicable) swapping their prefix from
 ``disallow`` to ``allow`` (and vice versa).
 
 
-Examples
-********
+Example ``mypy.ini``
+********************
 
 Here is an example of a ``mypy.ini`` file. To use this config file, place it at the root
 of your repo and run mypy.


Code review comments:
diff_hunk: @@ -3,17 +3,22 @@
 The mypy configuration file
 ===========================
 
-Mypy supports reading configuration settings from a file.  By default
-it uses the file ``mypy.ini`` with a fallback to ``.mypy.ini``, then ``pyproject.toml``,
-then ``setup.cfg`` in the current directory, then ``$XDG_CONFIG_HOME/mypy/config``, then
-``~/.config/mypy/config``, and finally ``.mypy.ini`` in the user home directory
-if none of them are found; the :option:`--config-file <mypy --config-file>` command-line flag can be used
-to read a different file instead (see :ref:`config-file-flag`).
+Mypy supports reading configuration settings from a file with the following precedence order:
+
+    1. ``./mypy.ini``
+    2. ``./.mypy.ini``
+    3. ``./pyproject.toml``
+    4. ``./setup.cfg``
+    5. ``$XDG_CONFIG_HOME/mypy/config``
+    6. ``~/.config/mypy/config``
+    7. ``~/.mypy.ini``
 
 It is important to understand that there is no merging of configuration
-files, as it would lead to ambiguity.  The :option:`--config-file <mypy --config-file>` flag
-has the highest precedence and must be correct; otherwise mypy will report
-an error and exit.  Without command line option, mypy will look for configuration files in the above mentioned order.
+files, as it would lead to ambiguity. The :option:`--config-file <mypy --config-file>`
+command-line flag (see :ref:`config-file-flag`) has the highest precedence and 
path: docs/source/config_file.rst
text: @user1:
preexisting, but the `:option:` role and this explicit reference link to basically the same place
```suggestion
command-line flag has the highest precedence and 
```