DOC: Additions/updates to documentation (#17150)

README.md

@@ -53,15 +53,15 @@
 <tr>
   <td>Conda</td>
   <td>
-    <a href="http://pandas.pydata.org">
+    <a href="https://pandas.pydata.org">
     <img src="http://pubbadges.s3-website-us-east-1.amazonaws.com/pkgs-downloads-pandas.png" alt="conda default downloads" />
     </a>
   </td>
 </tr>
 <tr>
   <td>Conda-forge</td>
   <td>
-    <a href="http://pandas.pydata.org">
+    <a href="https://pandas.pydata.org">
     <img src="https://anaconda.org/conda-forge/pandas/badges/downloads.svg" alt="conda-forge downloads" />
     </a>
   </td>
@@ -123,31 +123,31 @@ Here are just a few of the things that pandas does well:
     moving window linear regressions, date shifting and lagging, etc.
 
 
-   [missing-data]: http://pandas.pydata.org/pandas-docs/stable/missing_data.html#working-with-missing-data
-   [insertion-deletion]: http://pandas.pydata.org/pandas-docs/stable/dsintro.html#column-selection-addition-deletion
-   [alignment]: http://pandas.pydata.org/pandas-docs/stable/dsintro.html?highlight=alignment#intro-to-data-structures
-   [groupby]: http://pandas.pydata.org/pandas-docs/stable/groupby.html#group-by-split-apply-combine
-   [conversion]: http://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe
-   [slicing]: http://pandas.pydata.org/pandas-docs/stable/indexing.html#slicing-ranges
-   [fancy-indexing]: http://pandas.pydata.org/pandas-docs/stable/indexing.html#advanced-indexing-with-ix
-   [subsetting]: http://pandas.pydata.org/pandas-docs/stable/indexing.html#boolean-indexing
-   [merging]: http://pandas.pydata.org/pandas-docs/stable/merging.html#database-style-dataframe-joining-merging
-   [joining]: http://pandas.pydata.org/pandas-docs/stable/merging.html#joining-on-index
-   [reshape]: http://pandas.pydata.org/pandas-docs/stable/reshaping.html#reshaping-and-pivot-tables
-   [pivot-table]: http://pandas.pydata.org/pandas-docs/stable/reshaping.html#pivot-tables-and-cross-tabulations
-   [mi]: http://pandas.pydata.org/pandas-docs/stable/indexing.html#hierarchical-indexing-multiindex
-   [flat-files]: http://pandas.pydata.org/pandas-docs/stable/io.html#csv-text-files
-   [excel]: http://pandas.pydata.org/pandas-docs/stable/io.html#excel-files
-   [db]: http://pandas.pydata.org/pandas-docs/stable/io.html#sql-queries
-   [hdfstore]: http://pandas.pydata.org/pandas-docs/stable/io.html#hdf5-pytables
-   [timeseries]: http://pandas.pydata.org/pandas-docs/stable/timeseries.html#time-series-date-functionality
+   [missing-data]: https://pandas.pydata.org/pandas-docs/stable/missing_data.html#working-with-missing-data
+   [insertion-deletion]: https://pandas.pydata.org/pandas-docs/stable/dsintro.html#column-selection-addition-deletion
+   [alignment]: https://pandas.pydata.org/pandas-docs/stable/dsintro.html?highlight=alignment#intro-to-data-structures
+   [groupby]: https://pandas.pydata.org/pandas-docs/stable/groupby.html#group-by-split-apply-combine
+   [conversion]: https://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe
+   [slicing]: https://pandas.pydata.org/pandas-docs/stable/indexing.html#slicing-ranges
+   [fancy-indexing]: https://pandas.pydata.org/pandas-docs/stable/indexing.html#advanced-indexing-with-ix
+   [subsetting]: https://pandas.pydata.org/pandas-docs/stable/indexing.html#boolean-indexing
+   [merging]: https://pandas.pydata.org/pandas-docs/stable/merging.html#database-style-dataframe-joining-merging
+   [joining]: https://pandas.pydata.org/pandas-docs/stable/merging.html#joining-on-index
+   [reshape]: https://pandas.pydata.org/pandas-docs/stable/reshaping.html#reshaping-and-pivot-tables
+   [pivot-table]: https://pandas.pydata.org/pandas-docs/stable/reshaping.html#pivot-tables-and-cross-tabulations
+   [mi]: https://pandas.pydata.org/pandas-docs/stable/indexing.html#hierarchical-indexing-multiindex
+   [flat-files]: https://pandas.pydata.org/pandas-docs/stable/io.html#csv-text-files
+   [excel]: https://pandas.pydata.org/pandas-docs/stable/io.html#excel-files
+   [db]: https://pandas.pydata.org/pandas-docs/stable/io.html#sql-queries
+   [hdfstore]: https://pandas.pydata.org/pandas-docs/stable/io.html#hdf5-pytables
+   [timeseries]: https://pandas.pydata.org/pandas-docs/stable/timeseries.html#time-series-date-functionality
 
 ## Where to get it
 The source code is currently hosted on GitHub at:
-http://github.com/pandas-dev/pandas
+https://github.com/pandas-dev/pandas
 
 Binary installers for the latest released version are available at the [Python
-package index](http://pypi.python.org/pypi/pandas/) and on conda.
+package index](https://pypi.python.org/pypi/pandas) and on conda.
 
 ```sh
 # conda
@@ -161,11 +161,11 @@ pip install pandas
 
 ## Dependencies
 - [NumPy](http://www.numpy.org): 1.7.0 or higher
-- [python-dateutil](http://labix.org/python-dateutil): 1.5 or higher
-- [pytz](http://pytz.sourceforge.net)
+- [python-dateutil](https://labix.org/python-dateutil): 1.5 or higher
+- [pytz](https://pythonhosted.org/pytz)
     - Needed for time zone support with ``pandas.date_range``
 
-See the [full installation instructions](http://pandas.pydata.org/pandas-docs/stable/install.html#dependencies)
+See the [full installation instructions](https://pandas.pydata.org/pandas-docs/stable/install.html#dependencies)
 for recommended and optional dependencies.
 
 ## Installation from sources
@@ -197,13 +197,13 @@ mode](https://pip.pypa.io/en/latest/reference/pip_install.html#editable-installs
 pip install -e .
 ```
 
-See the full instructions for [installing from source](http://pandas.pydata.org/pandas-docs/stable/install.html#installing-from-source).
+See the full instructions for [installing from source](https://pandas.pydata.org/pandas-docs/stable/install.html#installing-from-source).
 
 ## License
-BSD
+[BSD 3](LICENSE)
 
 ## Documentation
-The official documentation is hosted on PyData.org: http://pandas.pydata.org/pandas-docs/stable/
+The official documentation is hosted on PyData.org: https://pandas.pydata.org/pandas-docs/stable
 
 The Sphinx documentation should provide a good starting point for learning how
 to use the library. Expect the docs to continue to expand as time goes on.
@@ -223,7 +223,7 @@ Most development discussion is taking place on github in this repo. Further, the
 ## Contributing to pandas
 All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome.
 
-A detailed overview on how to contribute can be found in the **[contributing guide.](http://pandas.pydata.org/pandas-docs/stable/contributing.html)**
+A detailed overview on how to contribute can be found in the **[contributing guide.](https://pandas.pydata.org/pandas-docs/stable/contributing.html)**
 
 If you are simply looking to start working with the pandas codebase, navigate to the [GitHub “issues” tab](https://github.com/pandas-dev/pandas/issues) and start looking through interesting issues. There are a number of issues listed under [Docs](https://github.com/pandas-dev/pandas/issues?labels=Docs&sort=updated&state=open) and [Difficulty Novice](https://github.com/pandas-dev/pandas/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty+Novice%22) where you could start out.
 

doc/source/gotchas.rst

@@ -144,7 +144,7 @@ To evaluate single-element pandas objects in a boolean context, use the method `
 Bitwise boolean
 ~~~~~~~~~~~~~~~
 
-Bitwise boolean operators like ``==`` and ``!=`` will return a boolean ``Series``,
+Bitwise boolean operators like ``==`` and ``!=`` return a boolean ``Series``,
 which is almost always what you want anyways.
 
 .. code-block:: python
@@ -194,7 +194,7 @@ For lack of ``NA`` (missing) support from the ground up in NumPy and Python in
 general, we were given the difficult choice between either
 
 - A *masked array* solution: an array of data and an array of boolean values
-  indicating whether a value
+  indicating whether a value is there or is missing
 - Using a special sentinel value, bit pattern, or set of sentinel values to
   denote ``NA`` across the dtypes
 
@@ -247,16 +247,16 @@ dtype in order to store the NAs. These are summarized by this table:
    ``integer``, cast to ``float64``
    ``boolean``, cast to ``object``
 
-While this may seem like a heavy trade-off, I have found very few
-cases where this is an issue in practice. Some explanation for the motivation
-here in the next section.
+While this may seem like a heavy trade-off, I have found very few cases where
+this is an issue in practice i.e. storing values greater than 2**53. Some
+explanation for the motivation is in the next section.
 
 Why not make NumPy like R?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Many people have suggested that NumPy should simply emulate the ``NA`` support
 present in the more domain-specific statistical programming language `R
-<http://r-project.org>`__. Part of the reason is the NumPy type hierarchy:
+<https://r-project.org>`__. Part of the reason is the NumPy type hierarchy:
 
 .. csv-table::
    :header: "Typeclass","Dtypes"
@@ -305,7 +305,7 @@ the ``DataFrame.copy`` method. If you are doing a lot of copying of DataFrame
 objects shared among threads, we recommend holding locks inside the threads
 where the data copying occurs.
 
-See `this link <http://stackoverflow.com/questions/13592618/python-pandas-dataframe-thread-safe>`__
+See `this link <https://stackoverflow.com/questions/13592618/python-pandas-dataframe-thread-safe>`__
 for more information.
 
 
@@ -332,5 +332,5 @@ using something similar to the following:
    s = pd.Series(newx)
 
 See `the NumPy documentation on byte order
-<http://docs.scipy.org/doc/numpy/user/basics.byteswapping.html>`__ for more
+<https://docs.scipy.org/doc/numpy/user/basics.byteswapping.html>`__ for more
 details.