PR: Baseline pass to fix/update existing content, copyedit, and conform to style guide #44
Conversation
|
@ccordoba12 Thanks for your feedback; good catches. Fixed all of it now. |
doc/ipythonconsole.rst
Outdated
| When working with scripts and modules in an interactive session, Python only loads a module from its source file once, the first time it is ``import``ed. | ||
| During this first ``import``, the bytecode (``.pyc`` file) is generated if necessary and the imported module object is cached in ``sys.modules``. | ||
| If you subsequently re-import the module anytime in the same session, this cached code object will be used even if its source code (``.py{w}`` file) has changed in the meantime. | ||
| While efficient for final production code, this behavior is often undesired when working with the Python interpreter interactively, such as when analyzing data or testing your own module. |
There was a problem hiding this comment.
Let's remove here with the Python interpreter and imply leave interactively.
There was a problem hiding this comment.
Yup, that sounds much better. Fixed.
doc/ipythonconsole.rst
Outdated
| During this first ``import``, the bytecode (``.pyc`` file) is generated if necessary and the imported module object is cached in ``sys.modules``. | ||
| If you subsequently re-import the module anytime in the same session, this cached code object will be used even if its source code (``.py{w}`` file) has changed in the meantime. | ||
| While efficient for final production code, this behavior is often undesired when working with the Python interpreter interactively, such as when analyzing data or testing your own module. | ||
| In effect, you're left with no way to update or modify any already-imported modules, aside from manually removing the relevant ``.pyc`` files, or completely restarting the console entirely. |
There was a problem hiding this comment.
Let's remove completely here.
There was a problem hiding this comment.
Two adverbs in one sentence seems too much to me :-)
There was a problem hiding this comment.
Yup :) Good catch; fixed.
|
@ccordoba12 Fixed your latest, thanks. |
doc/ipythonconsole.rst
Outdated
|
|
||
| Fortunately, in Spyder, there's an easy solution: the :guilabel:`User Module Reloader` (UMR), a Spyder-exclusive feature that, when enabled, automatically reloads modules right in the existing ``IPython`` shell whenever they are modified, without any of the downsides of the above workarounds. |
There was a problem hiding this comment.
This is not exactly true. The UMR only works when you run again a file with F5.
However, we also load the %autoreload IPython magic by default in all our kernels, which picks up changes immediately after a Python file has been modified and saved, as long as that file has been imported first.
There was a problem hiding this comment.
I think we should mention the distinction between the two here.
There was a problem hiding this comment.
I figured that making an explicit distinction would be mostly academic for the great majority of users and thus lumped them both under the UMR banner. However, in response to this, I re-wrote it to expose, explain and clarify it.
doc/options.rst
Outdated
|
|
||
| Spyder's command line options are the following: | ||
| Spyder's command line options including the following: |
There was a problem hiding this comment.
Thanks! Dumb mistake; fixed.
| --window-title=WINDOW_TITLE | ||
| String to show in the main window title | ||
| String to show in the window title, to identify the Spyder instance |
There was a problem hiding this comment.
This is missing
-p OPEN_PROJECT, --project=OPEN_PROJECT
Path that contains an Spyder project
doc/overview.rst
Outdated
| Key features: | ||
| * :doc:`editor`: | ||
|
|
||
| * Customizable syntax highlighting themes (Python, C/C++, Fortran) |
There was a problem hiding this comment.
I think (Python, C/C++, Fortran) is unnecessary here.
doc/overview.rst
Outdated
| * Automatic indentation after 'else', 'elif', 'finally', etc. | ||
| * Smart auto-indentation based on code structure | ||
| * Automatic insertion of colons after for, if, def, etc. | ||
| * Automatically fix mixed indentation, EoL characters and trailing spaces |
There was a problem hiding this comment.
I used EoL since of is not capitalized in Title Case (and thus generally shouldn't be in the acronym, to reflect its origins), but it seems the convention is EOL (EoL being more associated with End of Life). Fixed.
doc/overview.rst
Outdated
| * run in a new Python interpreter or in an existing Python interpreter or IPython client | ||
| * Python interpreter command line options | ||
| * Any number of individual consoles, each executed in a separate, isolated processes | ||
| * Each console uses the full IPython kernel as a back-end with a light GUI front-end |
There was a problem hiding this comment.
The hyphens are unnecessary here, so this needs to be
Each console uses a full IPython kernel as backend with a light GUI frontend
There was a problem hiding this comment.
I generally write them as one word as well, but all three (one word, two words, hyphen) are in common and interchangeable use and I was following the convention of the OpenStack Writing Style guide, which we generally follow as specified in our style guide (since its one of the most comprehensive, if not the most comprehensive one out there for a major Python project's documentation). Nevertheless, switched to "backend"/"frontend" for pedantry's sake.
There was a problem hiding this comment.
Not to mention its one more red underline to deal with in a spell checker.
doc/overview.rst
Outdated
| * *code completion* | ||
| * *calltips* | ||
| * *go-to-definition*: go to object (any symbol: function, class, attribute, etc.) definition by pressing Ctrl+Left mouse click on word or Ctrl+G (default shortcut) | ||
| * Lists all global variables, functions, classes, and their content |
There was a problem hiding this comment.
This is not true by default. What we show by default right now is iterables (lists, dicts, tuples), Numpy arrays and Dataframes.
There was a problem hiding this comment.
Perhaps it could be enough to remove all here, to not give the false impression that we show everything by default.
There was a problem hiding this comment.
Good point. Changed it to * Can list all global variables, functions, classes, and other objects, or filter them by several criteria
doc/overview.rst
Outdated
| * automatically unindent after 'else', 'elif', 'finally', etc. | ||
| * Provides documentation or source code for any Python object (class, function, module...) | ||
| * Can be triggered manually, on demand (:kbd:`Ctrl-I` by default) or automatically on typing a left parenthesis after a function name (optional) | ||
| * Real-time rendering and rich HTML display of many common docstring formats (powered by ``Sphinx``) |
There was a problem hiding this comment.
Right now we only support the numpydoc format.
There was a problem hiding this comment.
Ah; I though we supported googledoc too for some reason. Fixed.
doc/pylint.rst
Outdated
| by entering manually the Python module or package path - i.e. it works either | ||
| with `.py` (or `.pyw`) Python scripts or with whole Python packages | ||
| (directories containing an `__init__.py` script). | ||
| The **Static Code Analysis** module detects style issues, bad practices, potential bugs, and other quality problems in your code, all without having to actually execute it. |
There was a problem hiding this comment.
Please change module here to pane, to not give users the wrong impression that this is a Python module.
There was a problem hiding this comment.
Fixed; that was a mistype on my part. I intended to keep to the consistent convention of properly calling each a "pane". Thanks for the catch; I'll formally codify it in the style guide.
doc/pylint.rst
Outdated
| To go directly to the file and line in the :doc:`editor` highlighted by a failed check, just click its name. | ||
| You can click the dropdown or press the :kbd:`Down Arrow` key in the filename field to view results of previous analyses; the number of recent runs Spyder should remember can be customized in the :guilabel:`History` dialog from the :guilabel:`Static Code Analysis` context menu. | ||
| All standard checks are run by default. | ||
| You can turn certain messages off at the line, block or file/module level by adding a ``# pylinet: disable=insert, message-names, here`` comment at the respective level, or by editing the :file:`.pylintrc` configuration file in your user home directory (for more details on configuring Pylint, see the `Pylint documentation`_). |
There was a problem hiding this comment.
There's a little error and room for improvement here:
``# pylint: disable=<insert error code here>``
There was a problem hiding this comment.
Fixed the silly error.
I re-wrote the whole line; the problem with just the above is that using message names is not only supported, but officially preferred, and it also needs to specify that a comma separated list can (and often is) used. Thus:
You can turn certain messages off at the line, block or file/module level by adding a
``# pylint: disable=<list of message names>`` comment at the respective level, where the
``<...>`` portion should be replaced with a comma-separated list (or single value) without the
``<``/``>`` of Pylint message names (*e.g.* ``multiple-statements``, or ``fixme, line-too-long``;
you can also use error codes like ``C0321`` although names are preferred for clarity).
|
@CAM-Gerlach, I finished my review. Thanks a lot for your help, it's a huge improvement!! |
|
@ccordoba12 Thanks for all the review feedback! I'll go over and implement it immediately. |
|
@ccordoba12 Thanks, fixed everything you pointed out. |
Pull Request Checklist
Description of Changes
Here we go—the big kahuna. I don't like making a PR this big and monolithic, but the motivating issue required numerous cross-project changes to every file in at least three separate phases that would have blocked one another, and thus it would not have been possible to get this done for the 3.3 release otherwise. In addition, the nature of it meant that it centered around a number of changes that touched nearly every line and file, some multiple times, and thus would have taken much more effort to review them individually than together, especially considering the most effective way to review it is going to pretty much have to be looking at the rendered results, rather than going over the diffs line by line anyway, and viewing them in an incomplete state would have affected the accuracy and representatives of the review.
Finally, and most importantly, the somewhat less than reviewer friendly nature of this PR is a direct consequence of the major systemic changes made that will make it much easier to edit much smaller pieces of the docs in the future, and review them in a much more logical manner, all with a minimum of potential merge conflicts and extraneous diffs (most prominently, the switch from hard wrapping to line-breaks based on sentences, which is a far more natural order for a
git-based VCS). Therefore, the whole point of this PR is to avoid the need for anything like it anytime in the forseeable future, and keep all future PRs narrowly scoped, affecting as few files and lines as possible, solving one and only one issue, following a consistent style guide, not blocking one another, and easy to review even just via diffs.In any case, again, I highly recommend you review this PR via careful examination of the actual results (i.e. the docs in your web browser with
make html), since it should both be much easier to follow and review, and much more representative in terms of important things to look for; additionally, the source files were much more heavily checked over than the actual rendered docs, so there's more likely to be something visibly wrong there than the source. Aside from immediately visible changes, all the changes to the source are comprehensively described in the docs style guide, which you can view a rough draft of.Thanks, and looking forward to hearing your feedback.
EDIT: Thanks @sirredbeard for the suggestion on #46 .
Issue(s) Resolved
Fixes #13 Primary motivating issue motivating this PR
Fixes #15 Fixed, since it was a relatively small change of only a few lines
Fixes #16 Fixed as an unavoidable consequence of rewriting everything to fix 13
Fixes #43 Since its essentially a sub-issue of 13
Fixes #46 Incidentally, when running linkcheck and fixing links. Make some small additional changes per that issue.