Docs: cleanup related to generating sources+resources

src/sphinx/Detailed-Topics/Best-Practices.rst

@@ -56,7 +56,7 @@ clean up after a build and provides a single location to organize
 generated files. Any generated files that are specific to a Scala
 version should go in ``crossTarget`` for efficient cross-building.
 
-For generating sources and resources, see :ref:`the faq entry <generate-sources-resources>`.
+For generating sources and resources, see :doc:`/Howto/generatefiles`.
 
 Don't hard code
 ~~~~~~~~~~~~~~~

src/sphinx/Howto/generatefiles.rst

@@ -37,7 +37,7 @@ As a specific example, the following generates a hello world source file:
 
 Executing 'run' will print "Hi".  Change ``Compile`` to ``Test`` to make it a test source.  For efficiency, you would only want to generate sources when necessary and not every run.
 
-By default, generated sources are not included in the packaged source artifact.  To do so, add them as you would other mappings.  See ``Adding files to a package``.
+By default, generated sources are not included in the packaged source artifact.  To do so, add them as you would other mappings.  See :ref:`Adding files to a package <modify-package-contents>`.
 
 .. howto::
    :id: resources
@@ -73,4 +73,4 @@ As a specific example, the following generates a properties file containing the
 
 Change ``Compile`` to ``Test`` to make it a test resource.  Normally, you would only want to generate resources when necessary and not every run.
 
-By default, generated resources are not included in the packaged source artifact.  To do so, add them as you would other mappings.  See the ``Adding files to a package`` section.
+By default, generated resources are not included in the packaged source artifact.  To do so, add them as you would other mappings.  See :ref:`Adding files to a package <modify-package-contents>`.

src/sphinx/Howto/package.rst

@@ -71,6 +71,8 @@ The ``artifactName`` setting controls the name of generated packages.  See the :
    mappings in (Compile, packageBin) +=
       { ( baseDirectory.value / "example.txt") -> "out/example.txt" }
 
+.. _modify-package-contents:
+
 The contents of a package are defined by the ``mappings`` task, of type ``Seq[(File,String)]``.  The ``mappings`` task is a sequence of mappings from a file to include in the package to the path in the package.  See :doc:`/Detailed-Topics/Mapping-Files` for convenience functions for generating these mappings.  For example, to add the file ``in/example.txt`` to the main binary jar with the path "out/example.txt",
 
 ::

src/sphinx/faq.rst

@@ -282,53 +282,10 @@ to the ``managedSource`` directory, the mapping function would have to
 be adjusted to try relativizing against additional directories or
 something more appropriate for the generator.
 
-.. _generate-sources-resources:
-
 How can I generate source code or resources?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-sbt provides standard hooks for adding source or resource generation
-tasks. A generation task should generate sources in a subdirectory of
-``sourceManaged`` for sources or ``resourceManaged`` for resources and
-return a sequence of files generated. The key to add the task to is
-called ``sourceGenerators`` for sources and ``resourceGenerators`` for
-resources. It should be scoped according to whether the generated files
-are main (``Compile``) or test (``Test``) sources or resources. This
-basic structure looks like:
-
-::
-
-    sourceGenerators in Compile += <your Task[Seq[File]] here>
-
-For example, assuming a method
-``def makeSomeSources(base: File): Seq[File]``,
-
-::
-
-    sourceGenerators in Compile += Def.task {
-      makeSomeSources( (sourceManaged in Compile).value / "demo")
-    }
-
-As a specific example, the following generates a hello world source
-file:
-
-::
-
-    sourceGenerators in Compile += Def.task {
-      val file = (sourceManaged in Compile) / "demo" / "Test.scala"
-      IO.write(file, """object Test extends App { println("Hi") }""")
-      Seq(file)
-    }
-
-Executing 'run' will print "Hi". Change ``Compile`` to ``Test`` to make
-it a test source. To generate resources, change ``sourceGenerators`` to
-``resourceGenerators`` and ``sourceManaged`` to ``resourceManaged``.
-Normally, you would only want to generate sources when necessary and not
-every run.
-
-By default, generated sources and resources are not included in the
-packaged source artifact. To do so, add them as you would other
-mappings. See the ``Adding files to a package`` section.
+See :doc:`/Howto/generatefiles`.
 
 How can a task avoid redoing work if the input files are unchanged?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~