Commits

aura committed 7ca93d0

add documentation commands ... done with commands for now

  • Participants
  • Parent commits d1b949d

Comments (0)

Files changed (3)

source/manual/commands.xml

     <xi:include href="commands/make-cli.xml" />
     <xi:include href="commands/make-tests.xml" />
     <xi:include href="commands/run-tests.xml" />
-    <!-- <xi:include href="commands/make-docs.xml" /> -->
-    <!-- <xi:include href="commands/make-docbook.xml" /> -->
+    <xi:include href="commands/make-docs.xml" />
+    <xi:include href="commands/make-docbook.xml" />
     
 </chapter>

source/manual/commands/make-docbook.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<sect1
+    xml:id="commands.make-docbook"
+    xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+>
+    <title>Make DocBook Files</title>
+    
+    <cmdsynopsis>
+        <command>./script/solar make-docbook</command>
+        <arg choice="plain">--package-dir=<replaceable>/path/to/package-docs</replaceable></arg>
+        <arg choice="plain">--class-dir=<replaceable>/path/to/class-docs</replaceable></arg>
+        <arg choice="plain">--docbook-dir=<replaceable>/path/to/docbook-output</replaceable></arg>
+    </cmdsynopsis>
+    
+    <para>
+        This command reads the wiki-like class and package documentation files
+        generated by <command><link
+        linkend="commands.make-docs">make-docs</link></command> and transforms
+        them into DocBook sources suitable for processing by the <link
+        xlink:href="http://doc.php.net/phd/">PHP Documentation Project PhD
+        processor</link> or another DocBook processor.  It uses the
+        input documentation directories noted by <literal>--package-dir</literal>
+        and <literal>--class-dir</literal>, and saves the transformed output
+        files to the directory noted by <literal>--docbook-dir</literal>.
+    </para>
+    
+    <note><para>
+        You need not issue <command><link
+        linkend="commands.make-docs">make-docs</link></command> and then
+        <command>make-docbook</command> if you want DocBook files. You can
+        do the conversion all at once using <command><link
+        linkend="commands.make-docs">make-docs</link></command> by passing
+        the optional <literal>--docbook-dir</literal> value.
+    </para></note>
+</sect1>

source/manual/commands/make-docs.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<sect1
+    xml:id="commands.make-docs"
+    xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+>
+    <title>Make Wiki-Like Documentation</title>
+    
+    <cmdsynopsis>
+        <command>./script/solar make-docs</command>
+        <arg choice="plain"><replaceable>Vendor</replaceable></arg>
+        <arg choice="opt">--lint</arg>
+        <arg choice="plain">--package-dir=<replaceable>/path/to/package-output</replaceable></arg>
+        <arg choice="plain">--class-dir=<replaceable>/path/to/class-output</replaceable></arg>
+        <arg choice="opt">--docbook-dir=<replaceable>/path/to/docbook-output</replaceable></arg>
+    </cmdsynopsis>
+    
+    <para>
+        This command examines the docblock comments for all classes in the
+        named <filename><replaceable>Vendor</replaceable></filename> in
+        <filename><replaceable>SYSTEM</replaceable>/include/</filename>
+        directory. It then generates wiki-like documentation files for each
+        class, including information about its constants, configuration,
+        properties and methods. These wiki files can then be read by web
+        applcations to present them, or by CLI scripts to further transform
+        them into other formats.
+    </para>
+    
+    <para>
+        The documentation generated for the classes will be saved in the
+        directory specified by <literal>--class-dir</literal>. The package
+        documentation will be saved in the directory specified by
+        <literal>--package-dir</literal>.
+        If the optional <literal>--docbook-dir</literal> tag is passed, the
+        wiki-like documentation files will be transformed into DocBook sources
+        suitable for processing by the <link
+        xlink:href="http://doc.php.net/phd/">PHP Documentation Project PhD
+        processor</link> or another DocBook processor.
+    </para>
+    
+    <para>
+        As part of the documentation generating process, the command will
+        emit warnings when class docblocks appear incomplete.  If you want
+        to check the source documentation completeness without generating
+        any files, pass the <literal>--lint</literal> option.
+    </para>
+    
+    <para>
+        The parser recognizes a subset of JavaDoc/PhpDoc tags as defined in
+        <link
+        xlink:href="http://solarphp.com/class/Solar_Docs_Phpdoc">Solar_Docs_Phpdoc</link>.
+        The narrative text for comments uses the markup rules defined by <link
+        xlink:href="http://solarphp.com/class/Solar_Markdown_Apidoc">Solar_Markdown_Apidoc</link>.
+        For examples, see the Solar
+        codebase itself.
+    </para>
+
+</sect1>