Another approach to adding more documentation for --write-selected

docs/publish.rst

@@ -1,6 +1,9 @@
 Publish your site
 #################
 
+
+.. _site_generation:
+
 Site generation
 ===============
 
@@ -16,6 +19,17 @@ 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.
 
+It's also possible to only generate a single file while working on a single
+page. To do this, use the ``--write-selected`` argument, like so:
+
+    pelican --write-selected output/posts/2014/10/08/my-blog-title/index.html
+
+Note that this uses the path to the generated file. To determine that path, use
+the output of the ``--debug`` flag to determine the correct file name.
+``--write-selected`` can take a comma-separated list of paths, if desired, or
+can be configured as a setting. See: :ref:`writing_only_selected_content` for
+more details.
+
 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/quickstart.rst

@@ -57,7 +57,8 @@ warning related to feeds, but that is normal when developing locally and can be
 ignored for now.)
 
 To quickly iterate a single file while working on it, you can generate only a
-single file. See: :ref:`writing_only_selected_content`.
+single file. See: :ref:`writing_only_selected_content` and
+:ref:`site_generation`
 
 Preview your site
 -----------------

docs/settings.rst

@@ -808,15 +808,10 @@ entire site output is often unnecessary. By specifying only the
 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.
+accepts a comma-separated list of output file paths (See
+:ref:`site_generation` for details).
 
-An example of doing this might be:
-
-    pelican --write-selected output/posts/2014/10/08/in-re-nsl/index.html
-
-You can use the output of the ``--debug`` flag to determine the correct file
-names to provide to the ``--write-selected`` flag.
+By default this list is empty, so all output is written.
 
 Example settings
 ================