Merge pull request #64 from bjbford/casper-soak-test-ska

Fixed Sphinx documentation warnings for all docstrings.
casper-astro · Aug 12, 2018 · a3f1044 · a3f1044
2 parents 3e8d237 + 73660ad
commit a3f1044
Show file tree

Hide file tree

Showing 23 changed files with 397 additions and 414 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -17,16 +17,9 @@
 from sphinx.apidoc import main as sphinx_apidoc_main
 # add jasper_library directory to sys.path so autodoc can document its modules.
 jasper_library_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'jasper_library'))
-sys.path.append(jasper_library_path)
-# use sphinx-apidoc to automatically document modules, classes, functions, etc.
-# Code found here: https://github.com/rtfd/readthedocs.org/issues/1139
-def run_apidoc(_):
-    build_modules_dir = os.path.join(os.path.dirname(__file__), 'src', 'jasper_library_modules')
-    ignore_file  = 'conf.py'
-    # Using '--force' in order to regenerate modules on every build.
-    sphinx_apidoc_main(['-e', '-o',  build_modules_dir, jasper_library_path, ignore_file, '--force'])
-
-
+sys.path.insert(0, jasper_library_path)
+platform_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'jasper_library', 'platform'))
+sys.path.insert(1, platform_path)
 # Workaround to include __init__'s with sphinx-apidoc generated documnentation.
 # Code found here: https://stackoverflow.com/questions/5599254/how-to-use-sphinxs-autodoc-to-document-a-classs-init-self-method
 def skip(app, what, name, obj, skip, options):
@@ -35,10 +28,8 @@ def skip(app, what, name, obj, skip, options):
     return skip    
 
 def setup(app):
-    app.connect('builder-inited', run_apidoc)
     app.connect("autodoc-skip-member", skip)
 
-
 # -- Project information -----------------------------------------------------
 
 project = 'CASPER Toolflow'

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,4 +1,4 @@
 sphinx
 sphinx_rtd_theme
 recommonmark
-sphinx-markdown-tables==0.0.6
+sphinx-markdown-tables==0.0.6
diff --git a/docs/src/blockdocs/Fft_biplex_real_2x.rst b/docs/src/blockdocs/Fft_biplex_real_2x.rst
@@ -66,9 +66,9 @@ Mask Parameters
 | Input bit width    | input\_bit\_width  | The number of bits | To make optimal    |
 |                    |                    | in each real and   | use of BRAMs =>    |
 |                    |                    | imaginary sample   | 18                 |
-|                    |                    | as they are input  | | For low FFT      |
-|                    |                    | to the FFT. If bit |   noise =>         |
-|                    |                    | growth is not      | | 25               |
+|                    |                    | as they are input  | For low FFT        |
+|                    |                    | to the FFT. If bit | noise => 25        |
+|                    |                    | growth is not      |                    |
 |                    |                    | chosen, each FFT   |                    |
 |                    |                    | stage will round   |                    |
 |                    |                    | numbers back down  |                    |

diff --git a/docs/src/blockdocs/Fft_biplex_real_4x.rst b/docs/src/blockdocs/Fft_biplex_real_4x.rst
@@ -60,9 +60,9 @@ Mask Parameters
 | Input bit width    | input\_bit\_width  | The number of bits | To make optimal    |
 |                    |                    | in each real and   | use of BRAMs =>    |
 |                    |                    | imaginary sample   | 18                 |
-|                    |                    | as they are input  | | For low FFT      |
-|                    |                    | to the FFT. If bit |   noise =>         |
-|                    |                    | growth is not      | | 25               |
+|                    |                    | as they are input  | For low FFT        |
+|                    |                    | to the FFT. If bit | noise => 25        |
+|                    |                    | growth is not      |                    |
 |                    |                    | chosen, each FFT   |                    |
 |                    |                    | stage will round   |                    |
 |                    |                    | numbers back down  |                    |

diff --git a/docs/src/jasper_library_modules/castro.rst b/docs/src/jasper_library_modules/castro.rst
@@ -1,7 +1,6 @@
-castro module
-=============
+castro
+=======
 
 .. automodule:: castro
     :members:
-    :undoc-members:
-    :show-inheritance:
+    :undoc-members:
diff --git a/docs/src/jasper_library_modules/clk_factors.rst b/docs/src/jasper_library_modules/clk_factors.rst
diff --git a/docs/src/jasper_library_modules/constraints.rst b/docs/src/jasper_library_modules/constraints.rst
@@ -1,7 +1,6 @@
-constraints module
-==================
+constraints
+===========
 
 .. automodule:: constraints
     :members:
-    :undoc-members:
-    :show-inheritance:
+    :undoc-members:
diff --git a/docs/src/jasper_library_modules/exec_flow.rst b/docs/src/jasper_library_modules/exec_flow.rst
@@ -1,7 +1,6 @@
-exec\_flow module
-=================
+exec\_flow
+===========
 
 .. automodule:: exec_flow
     :members:
-    :undoc-members:
-    :show-inheritance:
+    :undoc-members:
diff --git a/docs/src/jasper_library_modules/helpers.rst b/docs/src/jasper_library_modules/helpers.rst
@@ -1,7 +1,6 @@
-helpers module
-==============
+helpers
+========
 
 .. automodule:: helpers
     :members:
-    :undoc-members:
-    :show-inheritance:
+    :undoc-members:
diff --git a/docs/src/jasper_library_modules/memory.rst b/docs/src/jasper_library_modules/memory.rst
@@ -1,7 +1,6 @@
-memory module
-=============
+memory
+=======
 
 .. automodule:: memory
     :members:
-    :undoc-members:
-    :show-inheritance:
+    :undoc-members:
diff --git a/docs/src/jasper_library_modules/modules.rst b/docs/src/jasper_library_modules/modules.rst
@@ -5,12 +5,11 @@ jasper_library
    :maxdepth: 4
 
    castro
-   clk_factors
    constraints
    exec_flow
    helpers
    memory
    platform
    toolflow
    verilog
-   yellow_blocks
+   yellow_blocks
diff --git a/docs/src/jasper_library_modules/platform.rst b/docs/src/jasper_library_modules/platform.rst
@@ -1,7 +1,6 @@
-platform module
-===============
+platform
+=========
 
 .. automodule:: platform
-    :members:
-    :undoc-members:
-    :show-inheritance:
+    :members: 
+    :undoc-members:
diff --git a/docs/src/jasper_library_modules/toolflow.rst b/docs/src/jasper_library_modules/toolflow.rst
@@ -1,7 +1,6 @@
-toolflow module
-===============
+toolflow
+=========
 
 .. automodule:: toolflow
     :members:
-    :undoc-members:
-    :show-inheritance:
+    :undoc-members:
diff --git a/docs/src/jasper_library_modules/verilog.rst b/docs/src/jasper_library_modules/verilog.rst
@@ -1,7 +1,6 @@
-verilog module
-==============
+verilog
+========
 
 .. automodule:: verilog
     :members:
-    :undoc-members:
-    :show-inheritance:
+    :undoc-members: