make chapel-py missing warnings better

Signed-off-by: Jade Abraham <[email protected]>

doc/.gitignore

@@ -29,3 +29,5 @@ man.rst
 /tutorial/workbooks/*.bbl
 /tutorial/workbooks/*.blg
 /sphinx/build
+
+chapel-py-api.rst

doc/rst/conf.py

@@ -14,7 +14,10 @@
 
 import sys
 import os
+import shutil
+import pathlib
 import sphinx.environment
+import sphinx.util.logging
 
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
@@ -24,15 +27,28 @@
 sys.path.insert(0, os.path.abspath('../'))
 sys.path.insert(0, os.path.abspath('./'))
 
+# to prevent failures if chapel-py is not built/installed, check if its installed
+# if installed, add the path and generate the rst file
+# if not installed, just create the file so that the build doesn't fail
 chapel_py_dir = os.path.abspath(
     "../../third-party/chpl-venv/install/chpl-frontend-py-deps-py"
     + str(sys.version_info.major)
     + str(sys.version_info.minor)
 )
 include_chapel_py_docs = False
+chapel_py_api_template = os.path.abspath("./tools/chapel-py/chapel-py-api-template")
+chapel_py_api_rst = os.path.abspath("./tools/chapel-py/chapel-py-api.rst")
 if os.path.exists(chapel_py_dir):
     sys.path.insert(0, chapel_py_dir)
     include_chapel_py_docs = True
+    shutil.copyfile(chapel_py_api_template, chapel_py_api_rst)
+else:
+    pathlib.Path(chapel_py_api_rst).touch()
+    msg = (
+        "chapel-py not built, skipping API docs generation. "
+        "Run `make chapel-py-venv` to build chapel-py."
+    )
+    sphinx.util.logging.getLogger(__name__).info(msg, color="red")
 
 # -- General configuration ------------------------------------------------
 
@@ -92,13 +108,12 @@ def setup(app):
 
     if include_chapel_py_docs:
         app.connect('autodoc-process-signature', process_signature)
-        app.tags.add('chpl_include_chapel_py_docs')
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8-sig'
+# source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
@@ -119,7 +134,7 @@ def setup(app):
 
 # The full version, including alpha/beta/rc tags.
 release = '2.3.0 (pre-release)'
-#release = '2.3.0'
+# release = '2.3.0'
 
 # General information about the project.
 project = u'Chapel Documentation'
@@ -132,13 +147,13 @@ def setup(app):
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#language = None
+# language = None
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
-#today = ''
+# today = ''
 # Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
+# today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -169,27 +184,27 @@ def setup(app):
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-#default_role = None
+# default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+# add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#add_module_names = True
+# add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
-#show_authors = False
+# show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-#pygments_style = 'sphinx'
+# pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+# modindex_common_prefix = []
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
+# keep_warnings = False
 
 
 # -- Options for HTML output ----------------------------------------------
@@ -213,22 +228,22 @@ def setup(app):
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+# html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+# html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 # We set this because the default title is repetitive
 html_title = 'Chapel Documentation {0}'.format(chplversion)
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+# html_short_title = None
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+# html_logo = None
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -243,44 +258,44 @@ def setup(app):
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
-#html_extra_path = []
+# html_extra_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+# html_last_updated_fmt = '%b %d, %Y'
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+# html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-#html_additional_pages = {}
+# html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_domain_indices = True
+# html_domain_indices = True
 
 # If false, no index is generated.
-#html_use_index = True
+# html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
-#html_split_index = False
+# html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+# html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+# html_show_copyright = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
-#html_use_opensearch = ''
+# html_use_opensearch = ''
 
 # This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
+# html_file_suffix = None
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'chapel'
@@ -309,23 +324,23 @@ def setup(app):
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-#latex_logo = None
+# latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-#latex_use_parts = False
+# latex_use_parts = False
 
 # If true, show page references after internal links.
-#latex_show_pagerefs = False
+# latex_show_pagerefs = False
 
 # If true, show URL addresses after external links.
-#latex_show_urls = False
+# latex_show_urls = False
 
 # Documents to append as an appendix to all manuals.
-#latex_appendices = []
+# latex_appendices = []
 
 # If false, no module index is generated.
-#latex_domain_indices = True
+# latex_domain_indices = True
 
 
 # -- Options for manual page output ---------------------------------------
@@ -338,7 +353,7 @@ def setup(app):
 ]
 
 # If true, show URL addresses after external links.
-#man_show_urls = False
+# man_show_urls = False
 
 
 # -- Options for Texinfo output -------------------------------------------
@@ -354,16 +369,16 @@ def setup(app):
 ]
 
 # Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
+# texinfo_appendices = []
 
 # If false, no module index is generated.
-#texinfo_domain_indices = True
+# texinfo_domain_indices = True
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
+# texinfo_show_urls = 'footnote'
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
+# texinfo_no_detailmenu = False
 
 # -- Custom options -------------------------------------------------------
 

doc/rst/tools/chapel-py/chapel-py-api-template

@@ -0,0 +1,23 @@
+API
+---
+
+.. automodule:: chapel
+   :member-order: bysource
+   :members:
+   :undoc-members:
+
+.. automodule:: chapel.visitor
+   :member-order: bysource
+   :members:
+   :undoc-members:
+
+.. automodule:: chapel.replace
+   :member-order: bysource
+   :members:
+   :undoc-members:
+
+.. automodule:: chapel.lsp
+   :member-order: bysource
+   :members:
+   :undoc-members:
+

doc/rst/tools/chapel-py/chapel-py.rst

@@ -482,32 +482,8 @@ script implements the following features:
                new_text = record_text.replace(" {" , ", " + tag_str + " {" , 1)
            else:
                new_text = record_text.replace(record.name(), record.name() + " : " + tag_str, 1)
-   
-           yield (record, new_text)
 
+           yield (record, new_text)
 
-.. only:: chpl_include_chapel_py_docs
-
-   API
-   ---
 
-   .. automodule:: chapel
-     :member-order: bysource
-     :members:
-     :undoc-members:
-
-   .. automodule:: chapel.visitor
-     :member-order: bysource
-     :members:
-     :undoc-members:
-
-   .. automodule:: chapel.replace
-     :member-order: bysource
-     :members:
-     :undoc-members:
-
-   .. automodule:: chapel.lsp
-     :member-order: bysource
-     :members:
-     :undoc-members:
-
+.. include:: ./chapel-py-api.rst