Merge pull request #3692 from mwichmann/docs-for-scons4

Documentation updates in preparation for 4.0

Author: bdbaddog

CHANGES.txt

@@ -172,7 +172,12 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Close various logfiles (trace, cache, taskmastertrace, configure)
       when done using atexit calls.
     - Rebase forked copy of shutil.copytree to Python 3.7 stlib version.
-
+    - Significant rework of documentation: API docs are now generated
+      using Sphinx; manpage and user guide now use more "standard"
+      markup elements (which could facilitate later conversion to a
+      different doc format, should that choice be made); significant
+      rewordings in manpage.  Manpage Examples moved to an external
+      repository / website (scons-cookbook.readthedocs.io).
 
 
 RELEASE 3.1.2 - Mon, 17 Dec 2019 02:06:27 +0000

SCons/Tool/compilation_db.xml

@@ -67,7 +67,7 @@ env.CompilationDatabase('my_output.json')
                 files will not show up in your output file.
             </para>
             <para>
-                New in &SCons; 4.0.0
+                <emphasis>Available since &scons; 4.0.</emphasis>
             </para>
         </summary>
     </builder>

bin/scons_dev_master.py

@@ -47,10 +47,8 @@
     #'tetex-bin',
     #'tetex-latex',
 
-    # for ubuntu 9.10 
-    # 'texlive-lang-french'
     'python3-sphinx',
-    'sphinx-rtd-theme-common',
+    'python3-sphinx-rtd-theme',
 
 ]
 

doc/generated/builders.gen

@@ -50,6 +50,39 @@ for the calling syntax and details.
 </para>
 </listitem>
   </varlistentry>
+  <varlistentry id="b-CompilationDatabase">
+    <term><function>CompilationDatabase</function>()</term>
+    <term><replaceable>env</replaceable>.<methodname>CompilationDatabase</methodname>()</term>
+    <listitem><para>
+                The <function>CompilationDatabase</function> builder writes a JSON formatted compilation
+                    database according to the
+                <ulink url="https://clang.llvm.org/docs/JSONCompilationDatabase.html">LLVM specification
+                </ulink> which is consumed by a number of clang tools, editors, and other tools.
+            </para>
+            <para>
+                If you don't specify any files, the builder will default to <filename>compile_commands.json</filename>.
+            </para>
+            <para>
+                If you specify a single file as below
+                <programlisting language="python">
+env.CompilationDatabase('my_output.json')
+                </programlisting>
+                SCons will automatically use that as the target file.
+                If you specify more than one source, the source list will be ignored.
+            </para>
+            <para>
+                You should not specify source files. The <function>CompilationDatabase</function> builder instruments SCons to collect them from all
+                the C, C++, assembly source/target pairs.
+            </para>
+            <para>
+                NOTE: You must load the <literal>compilation_db</literal> tool prior to specifying any part of your build or some source/target
+                files will not show up in your output file.
+            </para>
+            <para>
+                <emphasis>Available since <command>scons</command> 4.0.</emphasis>
+            </para>
+        </listitem>
+  </varlistentry>
   <varlistentry id="b-CXXFile">
     <term><function>CXXFile</function>()</term>
     <term><replaceable>env</replaceable>.<methodname>CXXFile</methodname>()</term>

doc/generated/builders.mod

@@ -10,6 +10,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 
 <!ENTITY b-CFile "<function xmlns='http://www.scons.org/dbxsd/v1.0'>CFile</function>">
 <!ENTITY b-Command "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Command</function>">
+<!ENTITY b-CompilationDatabase "<function xmlns='http://www.scons.org/dbxsd/v1.0'>CompilationDatabase</function>">
 <!ENTITY b-CXXFile "<function xmlns='http://www.scons.org/dbxsd/v1.0'>CXXFile</function>">
 <!ENTITY b-DocbookEpub "<function xmlns='http://www.scons.org/dbxsd/v1.0'>DocbookEpub</function>">
 <!ENTITY b-DocbookHtml "<function xmlns='http://www.scons.org/dbxsd/v1.0'>DocbookHtml</function>">
@@ -66,6 +67,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 
 <!ENTITY b-env-CFile "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.CFile</function>">
 <!ENTITY b-env-Command "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Command</function>">
+<!ENTITY b-env-CompilationDatabase "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.CompilationDatabase</function>">
 <!ENTITY b-env-CXXFile "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.CXXFile</function>">
 <!ENTITY b-env-DocbookEpub "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.DocbookEpub</function>">
 <!ENTITY b-env-DocbookHtml "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.DocbookHtml</function>">
@@ -128,6 +130,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 
 <!ENTITY b-link-CFile "<link linkend='b-CFile' xmlns='http://www.scons.org/dbxsd/v1.0'><function>CFile</function></link>">
 <!ENTITY b-link-Command "<link linkend='b-Command' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Command</function></link>">
+<!ENTITY b-link-CompilationDatabase "<link linkend='b-CompilationDatabase' xmlns='http://www.scons.org/dbxsd/v1.0'><function>CompilationDatabase</function></link>">
 <!ENTITY b-link-CXXFile "<link linkend='b-CXXFile' xmlns='http://www.scons.org/dbxsd/v1.0'><function>CXXFile</function></link>">
 <!ENTITY b-link-DocbookEpub "<link linkend='b-DocbookEpub' xmlns='http://www.scons.org/dbxsd/v1.0'><function>DocbookEpub</function></link>">
 <!ENTITY b-link-DocbookHtml "<link linkend='b-DocbookHtml' xmlns='http://www.scons.org/dbxsd/v1.0'><function>DocbookHtml</function></link>">
@@ -184,6 +187,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 
 <!ENTITY b-link-env-CFile "<link linkend='b-CFile' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.CFile</function></link>">
 <!ENTITY b-link-env-Command "<link linkend='b-Command' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Command</function></link>">
+<!ENTITY b-link-env-CompilationDatabase "<link linkend='b-CompilationDatabase' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.CompilationDatabase</function></link>">
 <!ENTITY b-link-env-CXXFile "<link linkend='b-CXXFile' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.CXXFile</function></link>">
 <!ENTITY b-link-env-DocbookEpub "<link linkend='b-DocbookEpub' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.DocbookEpub</function></link>">
 <!ENTITY b-link-env-DocbookHtml "<link linkend='b-DocbookHtml' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.DocbookHtml</function></link>">

doc/generated/examples/EnumVariable_map_1.xml

@@ -1,3 +1,3 @@
-<screen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.scons.org/dbxsd/v1.0" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q COLOR=navy foo.o</userinput>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q COLOR=navy foo.o</userinput>
 cc -o foo.o -c -DCOLOR="blue" foo.c
 </screen>

doc/generated/examples/addmethod_ex1_1.xml

@@ -1,4 +1,4 @@
-<screen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.scons.org/dbxsd/v1.0" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q /</userinput>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q /</userinput>
 cc -o hello.o -c hello.c
 cc -o hello hello.o
 Install file: "hello" as "/usr/bin/hello"

doc/generated/examples/addmethod_ex2_1.xml

@@ -1,4 +1,4 @@
-<screen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.scons.org/dbxsd/v1.0" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput>
 cc -o test_stuff.o -c test_stuff.c
 cc -o tests/test_stuff test_stuff.o
 </screen>

doc/generated/examples/addmethod_ex2_2.xml

@@ -1,4 +1,4 @@
-<screen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.scons.org/dbxsd/v1.0" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">C:\&gt;<userinput>scons -Q</userinput>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">C:\&gt;<userinput>scons -Q</userinput>
 rc /nologo /fores.res res.rc
 cl /Fotest_stuff.obj /c test_stuff.c /nologo
 link /nologo /OUT:tests\test_stuff.exe test_stuff.obj res.res

doc/generated/examples/alias_ex1_1.xml

@@ -1,4 +1,4 @@
-<screen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.scons.org/dbxsd/v1.0" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q install</userinput>
+<screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q install</userinput>
 cc -o hello.o -c hello.c
 cc -o hello hello.o
 Install file: "hello" as "/usr/bin/hello"