Fix generated documentation (#360)

* Fix some issues with builtin modules and fix some warnings * Move generated documentation files into dedicated folder Co-authored-by: Damien Nguyen <damien1@huawei.com>
ProjectQ-Framework · Mar 25, 2020 · dfff0f3 · dfff0f3
1 parent 89cb7fd
commit dfff0f3
Show file tree

Hide file tree

Showing 6 changed files with 37 additions and 37 deletions.
diff --git a/.gitignore b/.gitignore
@@ -71,6 +71,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_doc_gen/
 docs/doxygen
 
 # PyBuilder

diff --git a/docs/conf.py b/docs/conf.py
@@ -527,9 +527,11 @@ def linkcode_resolve(domain, info):
 # ------------------------------------------------------------------------------
 # Automatically generate ReST files for each package of ProjectQ
 
+docgen_path = os.path.join(os.path.dirname(os.path.abspath('__file__')),
+                           '_doc_gen')
+os.mkdir(docgen_path)
 for desc in descriptions:
-    fname = os.path.join(os.path.dirname(os.path.abspath('__file__')),
-                         'projectq.{}.rst'.format(desc.name))
+    fname = os.path.join(docgen_path, 'projectq.{}.rst'.format(desc.name))
     lines = None
     if os.path.exists(fname):
         with open(fname, 'r') as fd:

diff --git a/docs/package_description.py b/docs/package_description.py
@@ -6,8 +6,12 @@
 class PackageDescription(object):
     package_list = []
 
-    def __init__(self, name, desc='', module_special_members='__init__',
-                 submodule_special_members='', submodules_desc='',
+    def __init__(self,
+                 pkg_name,
+                 desc='',
+                 module_special_members='__init__',
+                 submodule_special_members='',
+                 submodules_desc='',
                  helper_submodules=None):
         """
         Args:
@@ -25,24 +29,24 @@ def __init__(self, name, desc='', module_special_members='__init__',
                             automodule_properties)
         """
 
-        self.name = name
+        self.name = pkg_name
         self.desc = desc
-        if name not in PackageDescription.package_list:
-            PackageDescription.package_list.append(name)
+        if pkg_name not in PackageDescription.package_list:
+            PackageDescription.package_list.append(pkg_name)
 
         self.module = sys.modules['projectq.{}'.format(self.name)]
         self.module_special_members = module_special_members
 
-        self.submodule_special_members = module_special_members
+        self.submodule_special_members = submodule_special_members
         self.submodules_desc = submodules_desc
 
         self.helper_submodules = helper_submodules
 
         module_root = os.path.dirname(self.module.__file__)
         sub = [(name, obj) for name, obj in inspect.getmembers(
-            self.module,
-            lambda obj: inspect.ismodule(obj) and module_root in obj.__file__)
-               if name[0] != '_']
+            self.module, lambda obj: inspect.ismodule(obj) and hasattr(
+                obj, '__file__') and module_root in obj.__file__)
+               if pkg_name[0] != '_']
 
         self.subpackages = []
         self.submodules = []
@@ -56,19 +60,10 @@ def __init__(self, name, desc='', module_special_members='__init__',
         self.subpackages.sort(key=lambda x: x[0].lower())
         self.submodules.sort(key=lambda x: x[0].lower())
 
-        self.members = [(name, obj)
-                        for name, obj in inspect.getmembers(
-                                self.module,
-                                lambda obj: (inspect.isclass(obj)
-                                             or inspect.isfunction(obj)
-                                             or isinstance(obj, (int,
-                                                                 float,
-                                                                 tuple,
-                                                                 list,
-                                                                 dict,
-                                                                 set,
-                                                                 frozenset,
-                                                                 str))))
+        self.members = [(name, obj) for name, obj in inspect.getmembers(
+            self.module, lambda obj:
+            (inspect.isclass(obj) or inspect.isfunction(obj) or isinstance(
+                obj, (int, float, tuple, list, dict, set, frozenset, str))))
                         if name[0] != '_']
         self.members.sort(key=lambda x: x[0].lower())
 
@@ -100,13 +95,13 @@ def get_ReST(self):
             new_lines.append('')
             if self.submodules:
                 for name, _ in self.submodules:
-                    new_lines.append('\tprojectq.{}.{}'.format(self.name,
-                                                               name))
+                    new_lines.append('\tprojectq.{}.{}'.format(
+                        self.name, name))
                 new_lines.append('')
             if self.members:
                 for name, _ in self.members:
-                    new_lines.append('\tprojectq.{}.{}'.format(self.name,
-                                                               name))
+                    new_lines.append('\tprojectq.{}.{}'.format(
+                        self.name, name))
                 new_lines.append('')
 
         if self.submodules:
@@ -121,8 +116,8 @@ def get_ReST(self):
                 new_lines.append('.. autosummary::')
                 new_lines.append('')
                 for name, _ in self.submodules:
-                    new_lines.append('    projectq.{}.{}'.format(self.name,
-                                                                 name))
+                    new_lines.append('    projectq.{}.{}'.format(
+                        self.name, name))
                 new_lines.append('')
 
             for name, _ in self.submodules:

diff --git a/docs/projectq.rst b/docs/projectq.rst
@@ -11,12 +11,12 @@ For a detailed documentation of a subpackage or module, click on its name below:
     :maxdepth: 1
     :titlesonly:
 
-    projectq.backends
-    projectq.cengines
-    projectq.libs
-    projectq.meta
-    projectq.ops
-    projectq.setups
-    projectq.types
+    _doc_gen/projectq.backends
+    _doc_gen/projectq.cengines
+    _doc_gen/projectq.libs
+    _doc_gen/projectq.meta
+    _doc_gen/projectq.ops
+    _doc_gen/projectq.setups
+    _doc_gen/projectq.types
 
 
diff --git a/projectq/meta/_loop.py b/projectq/meta/_loop.py
@@ -87,6 +87,7 @@ def run(self):
         engines, i.e., if
 
         .. code-block:: python
+
             is_meta_tag_supported(next_engine, LoopTag) == False
         """
         error_message = ("\n Error. Qubits have been allocated in with "

diff --git a/projectq/ops/_command.py b/projectq/ops/_command.py
@@ -30,6 +30,7 @@
 optimizer to cancel the following two gates
 
 .. code-block:: python
+
     Swap | (qubit1, qubit2)
     Swap | (qubit2, qubit1)