This commit is almost exclusively adding line breaks. The one exception is renaming link text in precommit.rst. (#166)

drewoldag · web-flow · commit b7c0a9c28ff7 · 2023-04-10T08:47:50.000-07:00
diff --git a/docs/practices/git-lfs.rst b/docs/practices/git-lfs.rst
@@ -4,7 +4,9 @@ Git Large File Support
 Quick Start
 -------------------------------------------------------------------------------
 
-After cloning a repository and connecting to the resulting working tree confirm that you have ``git-lfs`` and then issue ``git lfs install`` to install configuration and hooks and then ``git lfs track`` to designate targets for git-lfs.
+After cloning a repository and connecting to the resulting working tree confirm 
+that you have ``git-lfs`` and then issue ``git lfs install`` to install 
+configuration and hooks and then ``git lfs track`` to designate targets for git-lfs.
 
 .. code-block:: bash
 
@@ -26,12 +28,17 @@ After cloning a repository and connecting to the resulting working tree confirm
 What is it? Why do it?
 -------------------------------------------------------------------------------
 
-`Git-lfs <https://git-lfs.com/>`_ replaces large files such as datasets, and graphics with text pointers inside Git, while storing the file contents on a remote server.
-This can be very useful for projects that have large data files that change infrequently. It does require a remote that supports git-lfs and so if you are unsure about
-whether you want to use git-lfs you probably do not want to use it until you understand it better.
+`Git-lfs <https://git-lfs.com/>`_ replaces large files such as datasets, and 
+graphics with text pointers inside Git, while storing the file contents on a remote server.
+This can be very useful for projects that have large data files that change 
+infrequently. 
+It does require a remote that supports git-lfs and so if you are unsure about
+whether you want to use git-lfs you probably do not want to use it until you 
+understand it better.
 
 This template provides a starting point for using git-lfs with a project.
-Note that you need to install the program ``git-lfs`` separately as that is not easily done as part of the installation. See :ref:`get-git-lfs-label`.
+Note that you need to install the program ``git-lfs`` separately as that is not 
+easily done as part of the installation. See :ref:`get-git-lfs-label`.
 
 How to manage
 -------------------------------------------------------------------------------
@@ -73,8 +80,10 @@ and several other git servers do support git-lfs. If you use another remote you
 Designate files for git-lfs tracking
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 You will also want add paths to ``.gitattributes`` that designate the files git-lfs will manage for git.
-While you can edit ``.gitattributes`` directly there is a command that will make the needed changes and create the file if necessary.
-For example, if you want to specify that ``FITS`` files are handled by git-lfs then you might use these commands
+While you can edit ``.gitattributes`` directly there is a command that will make 
+the needed changes and create the file if necessary.
+For example, if you want to specify that ``FITS`` files are handled by git-lfs 
+then you might use these commands
 
 .. code-block:: bash
 
@@ -94,13 +103,18 @@ in the lsst developer documentation and adapt its recommendations to your projec
 Uninstall git-lfs from the repository
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you want to stop using git-lfs going forward then you can uninstall it. You should use the same options used on installation, in particular if you specified the ``--local`` option you should also specify it here. Probably it is safer to always include the ``--local`` option so you restrict impact to the current repository.
+If you want to stop using git-lfs going forward then you can uninstall it. 
+You should use the same options used on installation, in particular if you 
+specified the ``--local`` option you should also specify it here. 
+Probably it is safer to always include the ``--local`` option so you restrict 
+impact to the current repository.
 
 .. code-block:: bash
 
     git lfs uninstall --local
 
-Any files modified after uninstalling git-lfs will become part of the regular git repository but the git-lfs artifacts will remain.
+Any files modified after uninstalling git-lfs will become part of the regular 
+git repository but the git-lfs artifacts will remain.
 
 Note that we recommend against uninstalling git-lfs as it causes confusion.
 
@@ -110,7 +124,8 @@ You can see what files are controlled by git-lfs using the ``git lfs ls-files``
 
     git lfs ls-files
 
-Then if you want to copy them to the regular git repository you can change their modification dates using ``touch`` and commit the changes.
+Then if you want to copy them to the regular git repository you can change their 
+modification dates using ``touch`` and commit the changes.
 
 
 
diff --git a/docs/practices/linting.rst b/docs/practices/linting.rst
@@ -4,14 +4,25 @@ Linting
 What is it? Why do it?
 -------------------------------------------------------------------------------
 
-Linting is a form of static program checking, meaning that it analyzes code without running it.
-
-A linter checks code for code errors, violations of some agreed-upon coding standards, or gives its opinion on code smells. A "code smell" is when something isn't exactly **wrong**, but could be an indicator that your code is inefficient or could be refactored to be cleaner.
-
-When code is reliably run through a linter, then code reviewers can assume that the code they're looking at adheres to that agreed-upon coding standard. 
-A code reviewer won't be distracted by improper spacing, and can focus their reviewing effort on the meat of the code.
-
-There are two main linters suggested by this template: pylint and black. While they have a lot of the same opinions, we recommend picking a single standard for your project and sticking to it. If some folks use one linter, this may cause undue churn in your source files as each developer creates some formatting changes each time they touch a file (and then another developer undoes them the next time they touch the same file).
+Linting is a form of static program checking, meaning that it analyzes code 
+without running it.
+
+A linter checks code for code errors, violations of some agreed-upon coding 
+standards, or gives its opinion on code smells. A "code smell" is when something 
+isn't exactly **wrong**, but could be an indicator that your code is inefficient 
+or could be refactored to be cleaner.
+
+When code is reliably run through a linter, then code reviewers can assume that 
+the code they're looking at adheres to that agreed-upon coding standard. 
+A code reviewer won't be distracted by improper spacing, and can focus their 
+reviewing effort on the meat of the code.
+
+There are two main linters suggested by this template: pylint and black. While 
+they have a lot of the same opinions, we recommend picking a single standard for 
+your project and sticking to it. 
+If some folks use one linter, this may cause undue churn in your source files as 
+each developer creates some formatting changes each time they touch a file (and 
+then another developer undoes them the next time they touch the same file).
 
 
 How to modify/remove
diff --git a/docs/practices/overview.rst b/docs/practices/overview.rst
@@ -1,9 +1,11 @@
 Overview
 ===============================================================================
 
-The LINCC Frameworks team has selected some best practices for inclusion in this project template.
+The LINCC Frameworks team has selected some best practices for inclusion in 
+this project template.
 
-Here, we explain each of those best practices in more detail, and provide any additional pointers you might want as you work within these practices.
+Here, we explain each of those best practices in more detail, and provide any 
+additional pointers you might want as you work within these practices.
 
 Practices
 -------------------------------------------------------------------------------
diff --git a/docs/practices/pipx.rst b/docs/practices/pipx.rst
@@ -22,10 +22,12 @@ We use ``pipx`` to install Copier (the technology that powers our template) as
 a command line tool, so that we can call ``copier`` from any virtual environment.
 Beyond that, we don't use ``pipx`` for anything else in the template.
 
-In the :doc:`Getting Started <../source/overview>` section, we assume the use of ``pipx``. But you can use 
-``conda`` or ``pip`` if you'd rather have ``copier`` installed in a specific 
-environment. We have not yet documented the differences to the getting started 
-workflow that this would require.
+In the :doc:`Getting Started <../source/overview>` section, we assume the use 
+of ``pipx``. 
+But you can use ``conda`` or ``pip`` if you'd rather have ``copier`` installed 
+in a specific environment. 
+We have not yet documented the differences to the getting started workflow that 
+this would require.
 
 How to install ``pipx``
 -----------------------
diff --git a/docs/practices/precommit.rst b/docs/practices/precommit.rst
@@ -57,4 +57,5 @@ of these that are not useful for your project.
      - Ensures that automatically generated documentation and, optionally, jupyter notebooks can be built successfully.
 
 
-Many other pre-commit hooks exist, a partial list can be found `here <https://pre-commit.com/hooks.html>`_.
+Many other pre-commit hooks exist, a partial list can be found in the pre-commit 
+`documentation <https://pre-commit.com/hooks.html>`_.
diff --git a/docs/source/new_project.rst b/docs/source/new_project.rst
@@ -5,13 +5,17 @@ Starting a new project
 Create a new project from the template
 -------------------------------------------------------------------------------
 
-Choose where you would like to create your new project, and call copier with the template.
+Choose where you would like to create your new project, and call copier with 
+the template.
 
 .. code-block:: bash
 
     >> copier gh:lincc-frameworks/python-project-template <path/to/destination>
 
-Copier will ask you questions for how to set up the project. These questions will be used to fill in aspects of the project's configuration, including both metadata and parameters. Below we provide some high-level overview of the questions:
+Copier will ask you questions for how to set up the project. These questions 
+will be used to fill in aspects of the project's configuration, including both 
+metadata and parameters. Below we provide some high-level overview of the 
+questions:
 
 .. list-table::
    :header-rows: 1
@@ -44,27 +48,37 @@ Copier will ask you questions for how to set up the project. These questions wil
      - Support for large files for use in git. This option is primarily informational and no answer locks you in to using (or not using) git-lfs. Importantly, selecting this option does not install git-lfs for your project (see :doc:`Git_Large_File_Support <../practices/git-lfs>`).
 
 
-While these choices will provide the initial structure for your project, most can be changed later. See Copier's `documentation for changing answers to the question <https://copier.readthedocs.io/en/stable/updating/>`_.
+While these choices will provide the initial structure for your project, most 
+can be changed later. 
+See Copier's `documentation for changing answers to the question <https://copier.readthedocs.io/en/stable/updating/>`_.
 
-After providing answers to the prompts, Copier will hydrate a project template and save it in the specified location. Additionally Copier will run ``git init`` in the new project directory to initialize it as a local repository.
+After providing answers to the prompts, Copier will hydrate a project template 
+and save it in the specified location. Additionally Copier will run 
+``git init`` in the new project directory to initialize it as a local repository.
 
 Create a new environment
 ---------------------------
 
 If you are using `virtual environments <https://packaging.python.org/en/latest/glossary/#term-Virtual-Environment>`_ 
-create a new environment with your choice of environment tools (virtualenv, conda, etc.) and activate it. 
-This step is optional, but we recommend using virtual environments to better manage different project's dependencies. 
-See Python's `description of virtual environments <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/>`_ for more details.
+create a new environment with your choice of environment tools (virtualenv, 
+conda, etc.) and activate it. 
+This step is optional, but we recommend using virtual environments to better 
+manage different project's dependencies. 
+See Python's `description of virtual environments <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/>`_ 
+for more details.
 
 .. tip::
-  Projects using Python notebooks will need to have ``pandoc`` installed to convert notebooks to html locally. 
-  Pandoc is `available on conda-forge <https://github.com/conda-forge/pandoc-feedstock>`_, so conda can be a convenient way to keep these dependencies grouped together.
+  Projects using Python notebooks will need to have ``pandoc`` installed to 
+  convert notebooks to html locally. 
+  Pandoc is `available on conda-forge <https://github.com/conda-forge/pandoc-feedstock>`_, 
+  so conda can be a convenient way to keep these dependencies grouped together.
 
 Install your new package
 ----------------------------------------------------
 
 Go to the new package directory and install the newly created python package.
-Use ``pip`` to install both the standard set of dependencies as well as the ``[dev]`` dependencies.
+Use ``pip`` to install both the standard set of dependencies as well as the 
+``[dev]`` dependencies.
 
 .. note::
   Depending on your system you may not need the single quotes around ``'.[dev]'``.
@@ -85,12 +99,16 @@ Use ``pip`` to install both the standard set of dependencies as well as the ``[d
 Great, but don't stop here
 -------------------------------------------------------------------------------
 
-At this point, your new project is hydrated and ready for you to start coding. But there's a lot more that this template has to offer. Keep reading to find out more about built in pre-commit hooks, GitHub CI, automatic documentation, and more.
+At this point, your new project is hydrated and ready for you to start coding. 
+But there's a lot more that this template has to offer. 
+Keep reading to find out more about built in pre-commit hooks, GitHub CI, 
+automatic documentation, and more.
 
 Commit your new project locally
 -------------------------------------------------------------------------------
 
-Commit the project to your local version control like so to see the pre-commit checks run.
+Commit the project to your local version control like so to see the pre-commit 
+checks run.
 
 .. code-block:: bash
 
@@ -109,7 +127,9 @@ Create a new repository in GitHub: (`GitHub How-to <https://docs.github.com/en/g
     >> git remote add origin https://github.com/<the_remote_project>/<the_remote_repository>
     >> git push origin <local_branch_name>
 
-Notice that when you create a PR in GitHub, a set of tests for Continuous Integration starts up to verify that the project can build successfully and that all the unit tests pass. Neato!
+Notice that when you create a PR in GitHub, a set of tests for Continuous 
+Integration starts up to verify that the project can build successfully and 
+that all the unit tests pass. Neato!
 
 Install pre-commit
 ----------------------------
