Add more docs for --write-selected option

Refs #1495

docs/publish.rst

@@ -1,6 +1,8 @@
 Publish your site
 #################
 
+.. _site_generation:
+
 Site generation
 ===============
 
@@ -16,6 +18,18 @@ folder, using the default theme to produce a simple site. The default theme
 consists of very simple HTML without styling and is provided so folks may use
 it as a basis for creating their own themes.
 
+When working on a single article or page, it is possible to generate only the
+file that corresponds to that content. To do this, use the ``--write-selected``
+argument, like so::
+
+    pelican --write-selected output/posts/my-post-title.html
+
+Note that you must specify the path to the generated *output* file — not the
+source content. To determine the output file path, use the ``--debug`` flag to
+determine the correct file name and location. If desired, ``--write-selected``
+can take a comma-separated list of paths or can be configured as a setting.
+(See: :ref:`writing_only_selected_content`)
+
 You can also tell Pelican to watch for your modifications, instead of
 manually re-running it every time you want to see your changes. To enable this,
 run the ``pelican`` command with the ``-r`` or ``--autoreload`` option.

docs/settings.rst

@@ -1212,7 +1212,8 @@ desired files as output paths in the ``WRITE_SELECTED`` list,
 **only** those files will be written. This list can be also specified
 on the command line using the ``--write-selected`` option, which
 accepts a comma-separated list of output file paths. By default this
-list is empty, so all output is written.
+list is empty, so all output is written. See :ref:`site_generation` for
+more details.
 
 
 Example settings