[DOC] add page for LOFAR and experiment-specific features

documentation/make_docs.py

@@ -54,6 +54,11 @@
             "Do not delete existing html files and build only pages which have changed."
             " Useful if you are only modifying or adding (not moving/removing) pages.")
     )
+    argparser.add_argument(
+        '--skip-apidoc', default=False, const=True, action='store_const', help=(
+            "Skip the compilation of the automatic API documentation. "
+            "Speeds up the compilation of the documentation if no changes were made to the code.")
+    )
     argparser.add_argument(
         '--debug', '-v', default=0, action='count',
         help="Store full debugging output in make_docs.log."
@@ -73,42 +78,42 @@
 
     doc_path = os.path.dirname(os.path.realpath(__file__))
     os.chdir(doc_path)
-
-    # we exclude scripts, examples and tests from the code documentation,
-    # as apidoc doesn't really handle those well
-    exclude_modules = []
-    exclude_modules.append('../**/test')
-    exclude_modules.append('../**/tests')
-    exclude_modules.append('../**/scripts')
-    exclude_modules.append('../**/examples')
-    exclude_modules.append('../**/eventbrowser') 
-    exclude_modules.append('../**/setup.py')
-    exclude_modules.append('../**/CPPAnalyticRayTracing') # C code also doesn't work right now
-    exclude_modules.append('../**/araroot') # this doesn't work because we don't have the .so files to read ARA data
-
-    # create the automatic code documentation with apidoc
-    for module in ['NuRadioReco', 'NuRadioMC']:
-        output_folder = 'source/{}/apidoc'.format(module)
-        if os.path.exists(output_folder):
-            if not parsed_args.no_clean: # remove old apidoc folder
-                logger.info('Removing old apidoc folder: {}'.format(output_folder))
-                subprocess.check_output(['rm', '-rf', output_folder])
-
-        module_path = '../{}/'.format(module)
-
-        logger.info("Creating automatic documentation files with apidoc:")
-        logger.info("excluding modules: {}".format(exclude_modules))
-        subprocess.run(
-            [
-                'sphinx-apidoc', '-efMT', '--ext-autodoc', '--ext-intersphinx',
-                '--ext-coverage', '--ext-githubpages', '-o', output_folder,
-                module_path, *exclude_modules
-            ], stdout=pipe_stdout
-        )
-        # We don't use the top level NuRadioReco.rst / NuRadioMC.rst toctrees,
-        # so we remove them to eliminate a sphinx warning
-        subprocess.check_output([
-            'rm', os.path.join(output_folder, '{}.rst'.format(module))])
+    if not parsed_args.skip_apidoc:
+        # we exclude scripts, examples and tests from the code documentation,
+        # as apidoc doesn't really handle those well
+        exclude_modules = []
+        exclude_modules.append('../**/test')
+        exclude_modules.append('../**/tests')
+        exclude_modules.append('../**/scripts')
+        exclude_modules.append('../**/examples')
+        exclude_modules.append('../**/eventbrowser')
+        exclude_modules.append('../**/setup.py')
+        exclude_modules.append('../**/CPPAnalyticRayTracing') # C code also doesn't work right now
+        exclude_modules.append('../**/araroot') # this doesn't work because we don't have the .so files to read ARA data
+
+        # create the automatic code documentation with apidoc
+        for module in ['NuRadioReco', 'NuRadioMC']:
+            output_folder = 'source/{}/apidoc'.format(module)
+            if os.path.exists(output_folder):
+                if not parsed_args.no_clean: # remove old apidoc folder
+                    logger.info('Removing old apidoc folder: {}'.format(output_folder))
+                    subprocess.check_output(['rm', '-rf', output_folder])
+
+            module_path = '../{}/'.format(module)
+
+            logger.info("Creating automatic documentation files with apidoc:")
+            logger.info("excluding modules: {}".format(exclude_modules))
+            subprocess.run(
+                [
+                    'sphinx-apidoc', '-efMT', '--ext-autodoc', '--ext-intersphinx',
+                    '--ext-coverage', '--ext-githubpages', '-o', output_folder,
+                    module_path, *exclude_modules
+                ], stdout=pipe_stdout
+            )
+            # We don't use the top level NuRadioReco.rst / NuRadioMC.rst toctrees,
+            # so we remove them to eliminate a sphinx warning
+            subprocess.check_output([
+                'rm', os.path.join(output_folder, '{}.rst'.format(module))])
 
     if not parsed_args.no_clean:
         logger.info('Removing old \'build\' directory...')

documentation/source/Experiments/lofar/overview.rst

@@ -0,0 +1,11 @@
+LOFAR
+=====
+
+NuRadioReco is also used for analysis of LOFAR data. To this end, it
+includes some LOFAR-specific modules.
+
+To **read** LOFAR data, use the :py:mod:`readLOFARData <NuRadioReco.modules.io.LOFAR.readLOFARData>`
+module.
+
+For analysis and reconstruction of LOFAR data, we use the modules in
+:py:mod:`NuRadioReco.modules.LOFAR <NuRadioReco.modules.LOFAR>`

documentation/source/Experiments/welcome_page.rst

@@ -0,0 +1,16 @@
+Experiment-specific features
+============================
+
+NuRadioMC (and NuRadioReco) are used by several different experiments.
+To facilitate this, NuRadioReco contains several experiment-specific
+features. Most of these are included under ``NuRadioReco.modules.<EXPERIMENT>``
+for analysis features, and readers for the raw experiment data under
+``NuRadioReco.modules.io.<EXPERIMENT>``.
+
+More information about the features available for each experiment
+are available on the pages below.
+
+.. toctree::
+    :maxdepth: 1
+
+    lofar/overview

documentation/source/main.rst

@@ -13,6 +13,7 @@ Welcome to NuRadio's documentation!
    Introduction/pages/welcome_page.rst
    NuRadioReco/pages/welcome_page.rst
    NuRadioMC/pages/welcome_page.rst
+   Experiments/welcome_page.rst
 
 Indices and tables
 ==================