docs: Extended README for sphinx docs.

1 files changed, 32 insertions, 1 deletions

diff --git a/docs/sphinx/README b/docs/sphinx/README
index 31fd47fe2..c3ac38264 100644
--- a/docs/sphinx/README
+++ b/docs/sphinx/README
@@ -13,7 +13,7 @@ Sphinx takes this process one step farther by reading the docstrings
 of all Python blocks and creating its own manual. This has two
 benefits. First, the Sphinx documentation looks nice and is formatted
 in such a way that Python users of GNU Radio can easy see the module
-structure and hierarchy. It also allows not only takes the Doxygen
+structure and hierarchy. It also not only takes the Doxygen
 documentation from C++, but it also allows us to take any Python files
 and include their documentation. 
 
@@ -36,3 +36,34 @@ The run_sphinx_build.sh outputs the manual into
 $builddir/docs/sphinx/sphinx_out. Open up the index.html file in a
 browser to view it.
 
+ADDING NEW CONTENT TO THE SPHINX MANUAL
+Although the content of the sphinx manual is automatically generated,
+new blocks are not automatically added to the generated documentation.
+The procedure for adding new content is best illustrated with two
+examples.
+
+1) Adding a new C++ signal processing block gnuradio.gr.myslicer
+   Edit file gnuradio/docs/sphinx/source/gr/index.rst and add the line
+   >   gnuradio.gr.myslicer
+   under the "Slicing and Dicing Streams" subheading.
+   Edit file gnuradio/docs/sphinx/source/gr/slicedice_blk.rst and add
+   the line
+   >.. autoblock:: gnuradio.gr.myslicer
+
+2) Adding a new python hierarchical block gnuradio.digital.mymod
+   Edit file gnruadio/docs/sphinx/source/digital/index.rst and add the
+   line
+   >   gnuradio.digital.mymod
+   under the "Signal Processing Blocks" subheading.
+   Edit file gnuradio/docs/sphinx/source/digital/blocks.rst and add
+   the line
+   >.. autopyblock:: gnuradio.digital.mymod
+   Notice that the 'autopyblock' directive is used rather than the
+   'autoblock' directive.  This lets sphinx know that it is displaying
+   a python hierarchical signal processing block so that it can format
+   it appropriately.
+
+The process for documenting objects that are not signal processing blocks is
+similar but rather than using the 'autoblock' and 'autopyblock' directives
+the standard sphinx directives such as 'autofunction' and 'autoclass' can
+be used.
\ No newline at end of file