Exemple #1
0
def generate_doc_types_json(modules, types_file_path):
    doc_types_list = [{
        'id': 'gcloud',
        'contents': 'index.json',
        'title': 'gcloud'
    }]

    for module_name in modules:
        if module_name == 'gcloud.__init__':
            continue

        module_title = module_name.replace('.__init__', '').split('.')
        module_contents = (module_name.replace('.', '/').replace(
            '__init__', 'index'))

        if len(module_name.split('.')) > 2:
            module_id = module_name.replace('.', '/')
        else:
            module_id = (module_name.replace('.', '/'))

        module_contents += '.json'

        doc_type_object = build_type(module_id.replace('/__init__', ''),
                                     module_title, module_contents)

        doc_types_list.append(doc_type_object)

        pdoc_module = pdoc.Module(pdoc.import_module(module_name),
                                  allsubmodules=True)
        for c in pdoc_module.classes():
            generate_doc_types_classes_json(c, doc_types_list)

    write_docs_file(types_file_path, json.dumps(doc_types_list))
Exemple #2
0
 def test__all__(self):
     module = pdoc.import_module(EXAMPLE_MODULE + '.index')
     with patch.object(module, '__all__', ['B'], create=True):
         mod = pdoc.Module(module)
         with self.assertWarns(UserWarning):  # Only B is used but __pdoc__ contains others
             pdoc.link_inheritance()
         self.assertEqual(list(mod.doc.keys()), ['B'])
def generate_doc_types_json(modules, types_file_path):
    doc_types_list = [{
        'id': 'google-cloud',
        'contents': 'index.json',
        'title': 'google-cloud'
    }]

    for module_name in modules:
        if module_name == 'google.cloud.__init__':
            continue

        module_title = module_name.replace('.__init__', '').split('.')
        module_contents = (module_name.replace('.', '/')
                           .replace('__init__', 'index'))

        if len(module_name.split('.')) > 2:
            module_id = module_name.replace('.', '/')
        else:
            module_id = (module_name.replace('.', '/'))

        module_contents += '.json'

        doc_type_object = build_type(module_id.replace('/__init__', ''),
                                     module_title, module_contents)

        doc_types_list.append(doc_type_object)

        pdoc_module = pdoc.Module(pdoc.import_module(module_name),
                                  allsubmodules=True)
        for c in pdoc_module.classes():
            generate_doc_types_classes_json(c, doc_types_list)

    write_docs_file(types_file_path,
                    json.dumps(doc_types_list))
    def do_GET(self):
        # Deny favicon shortcut early.
        if self.path == "/favicon.ico":
            return None

        importlib.invalidate_caches()
        code = 200
        if self.path == "/":
            modules = [pdoc.import_module(module, reload=True)
                       for module in self.args.modules]
            modules = sorted((module.__name__, inspect.getdoc(module))
                             for module in modules)
            out = pdoc._render_template('/html.mako',
                                        modules=modules,
                                        **self.template_config)
        elif self.path.endswith(".ext"):
            # External links are a bit weird. You should view them as a giant
            # hack. Basically, the idea is to "guess" where something lives
            # when documenting another module and hope that guess can actually
            # track something down in a more global context.
            #
            # The idea here is to start specific by looking for HTML that
            # exists that matches the full external path given. Then trim off
            # one component at the end and try again.
            #
            # If no HTML is found, then we ask `pdoc` to do its thang on the
            # parent module in the external path. If all goes well, that
            # module will then be able to find the external identifier.

            import_path = self.path[:-4].lstrip("/")
            resolved = self.resolve_ext(import_path)
            if resolved is None:  # Try to generate the HTML...
                print("Generating HTML for %s on the fly..." % import_path, file=sys.stderr)
                try:
                    out = pdoc.html(import_path.split(".")[0], **self.template_config)
                except Exception as e:
                    print('Error generating docs: {}'.format(e), file=sys.stderr)
                    # All hope is lost.
                    code = 404
                    out = "External identifier <code>%s</code> not found." % import_path
            else:
                return self.redirect(resolved)
        # Redirect '/pdoc' to '/pdoc/' so that relative links work
        # (results in '/pdoc/cli.html' instead of 'cli.html')
        elif not self.path.endswith(('/', '.html')):
            return self.redirect(self.path + '/')
        # Redirect '/pdoc/index.html' to '/pdoc/' so it's more pretty
        elif self.path.endswith(pdoc._URL_PACKAGE_SUFFIX):
            return self.redirect(self.path[:-len(pdoc._URL_PACKAGE_SUFFIX)] + '/')
        else:
            try:
                out = self.html()
            except ImportError:
                code = 404
                out = "Module <code>%s</code> not found." % self.import_path_from_req_url

        self.send_response(code)
        self.send_header("Content-type", "text/html; charset=utf-8")
        self.end_headers()
        self.echo(out)
Exemple #5
0
 def test_inherited_members(self):
     mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
     pdoc.link_inheritance()
     a = mod.doc['A']
     b = mod.doc['B']
     self.assertEqual(b.inherited_members(), [(a, [a.doc['inherited'],
                                                   a.doc['overridden_same_docstring']])])
     self.assertEqual(a.inherited_members(), [])
Exemple #6
0
    def test_to_html_refname_warning(self):
        mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))

        def f():
            """Reference to some `example_pkg.nonexisting` object"""

        mod.doc['__f'] = pdoc.Function('__f', mod, f)
        with self.assertWarns(ReferenceWarning) as cm:
            mod.html()
        del mod.doc['__f']
        self.assertIn('example_pkg.nonexisting', cm.warning.args[0])
Exemple #7
0
    def test_reST_include(self):
        expected = '''<pre><code class="python">    x = 2
</code></pre>

<p>1
x = 2
x = 3
x =</p>'''
        mod = pdoc.Module(
            pdoc.import_module(
                os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE, '_reST_include',
                             'test.py')))
        text = inspect.getdoc(mod.obj)
        html = to_html(text, module=mod)
        self.assertEqual(html, expected)

        # Ensure includes are resolved within docstrings already,
        # e.g. for `pdoc.html_helpers.extract_toc()` to work
        self.assertIn('Command-line interface',
                      pdoc.Module(pdoc.import_module(pdoc)).docstring)
Exemple #8
0
 def test_namespace(self):
     # Test the three namespace types
     # https://packaging.python.org/guides/packaging-namespace-packages/#creating-a-namespace-package
     for i in range(1, 4):
         path = os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE, '_namespace',
                             str(i))
         with patch.object(
                 sys, 'path',
             [os.path.join(path, 'a'),
              os.path.join(path, 'b')]):
             mod = pdoc.Module(pdoc.import_module('a.main'))
             self.assertIn('D', mod.doc)
Exemple #9
0
    def test_find_ident(self):
        mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
        self.assertIsInstance(mod.find_ident('subpkg'), pdoc.Module)
        mod = pdoc.Module(pdoc)
        self.assertIsInstance(mod.find_ident('subpkg'), pdoc.External)

        self.assertIsInstance(mod.find_ident(EXAMPLE_MODULE + '.subpkg'), pdoc.Module)

        nonexistent = 'foo()'
        result = mod.find_ident(nonexistent)
        self.assertIsInstance(result, pdoc.External)
        self.assertEqual(result.name, nonexistent)
Exemple #10
0
    def test_link_inheritance(self):
        mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
        with warnings.catch_warnings(record=True) as w:
            pdoc.link_inheritance()
            pdoc.link_inheritance()
        self.assertFalse(w)

        mod._is_inheritance_linked = False
        with self.assertWarns(UserWarning):
            pdoc.link_inheritance()

        # Test inheritance across modules
        pdoc.reset()
        mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE + '._test_linking'))
        pdoc.link_inheritance()
        a = mod.doc['a'].doc['A']
        b = mod.doc['b'].doc['B']
        c = mod.doc['b'].doc['c'].doc['C']
        self.assertEqual(b.inherits, a)
        self.assertEqual(b.doc['a'].inherits, a.doc['a'])
        self.assertEqual(b.doc['c'].inherits, c.doc['c'])
Exemple #11
0
    def test_reST_include(self):
        expected = '''<pre><code class="python">    x = 2
</code></pre>

<p>1
x = 2
x = 3
x =</p>'''
        mod = pdoc.Module(pdoc.import_module(
            os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE, '_reST_include', 'test.py')))
        text = inspect.getdoc(mod.obj)
        html = to_html(text, module=mod)
        self.assertEqual(html, expected)
Exemple #12
0
 def test_module(self):
     modules = {
         EXAMPLE_MODULE: ('', ('index', 'module', 'subpkg', 'subpkg2')),
         os.path.join(EXAMPLE_MODULE, 'subpkg2'): ('.subpkg2', ('subpkg2.module',)),
     }
     with chdir(TESTS_BASEDIR):
         for module, (name_suffix, submodules) in modules.items():
             with self.subTest(module=module):
                 m = pdoc.Module(pdoc.import_module(module))
                 self.assertEqual(repr(m), "<Module '{}'>".format(m.obj.__name__))
                 self.assertEqual(m.name, EXAMPLE_MODULE + name_suffix)
                 self.assertEqual(sorted(m.name for m in m.submodules()),
                                  [EXAMPLE_MODULE + '.' + m for m in submodules])
Exemple #13
0
    def test__pdoc__dict(self):
        module = pdoc.import_module(EXAMPLE_MODULE)
        with patch.object(module, '__pdoc__', {'B': False}):
            mod = pdoc.Module(module)
            pdoc.link_inheritance()
            self.assertIn('A', mod.doc)
            self.assertNotIn('B', mod.doc)

        with patch.object(module, '__pdoc__', {'B.__init__': False}):
            mod = pdoc.Module(module)
            pdoc.link_inheritance()
            self.assertIn('B', mod.doc)
            self.assertNotIn('__init__', mod.doc['B'].doc)
            self.assertIsInstance(mod.find_ident('B.__init__'), pdoc.External)
Exemple #14
0
    def check_modified(self):
        try:
            module = pdoc.import_module(self.import_path_from_req_url)
            new_etag = str(os.stat(module.__file__).st_mtime)
        except ImportError:
            return 404

        old_etag = self.headers.get('If-None-Match', new_etag)
        if old_etag == new_etag:
            # Don't log repeating checks
            self.log_request = lambda *args, **kwargs: None
            return 304

        return 205
Exemple #15
0
    def test_link_inheritance(self):
        mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
        with warnings.catch_warnings(record=True) as w:
            pdoc.link_inheritance()
            pdoc.link_inheritance()
        self.assertFalse(w)

        mod._is_inheritance_linked = False
        with self.assertWarns(UserWarning):
            pdoc.link_inheritance()

        # Test inheritance across modules
        pdoc.reset()
        mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE + '._test_linking'))
        pdoc.link_inheritance()
        a = mod.doc['a'].doc['A']
        b = mod.doc['b'].doc['B']
        c = mod.doc['b'].doc['c'].doc['C']
        self.assertEqual(b.doc['a'].inherits, a.doc['a'])
        self.assertEqual(b.doc['c'].inherits, c.doc['c'])
        # While classes do inherit from superclasses, they just shouldn't always
        # say so, because public classes do want to be exposed and linked to
        self.assertNotEqual(b.inherits, a)
Exemple #16
0
    def test_readonly_value_descriptors(self):
        pdoc.reset()
        mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
        var = mod.doc['B'].doc['ro_value_descriptor']
        self.assertIsInstance(var, pdoc.Variable)
        self.assertTrue(var.instance_var)
        self.assertEqual(var.docstring, """ro_value_descriptor docstring""")
        self.assertTrue(var.source)

        var = mod.doc['B'].doc['ro_value_descriptor_no_doc']
        self.assertIsInstance(var, pdoc.Variable)
        self.assertTrue(var.instance_var)
        self.assertEqual(var.docstring, """Read-only value descriptor""")
        self.assertTrue(var.source)
Exemple #17
0
    def test_url(self):
        mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
        pdoc.link_inheritance()

        c = mod.doc['D']
        self.assertEqual(c.url(), 'example_pkg/index.html#example_pkg.D')
        self.assertEqual(c.url(link_prefix='/'), '/example_pkg/index.html#example_pkg.D')
        self.assertEqual(c.url(relative_to=c.module), '#example_pkg.D')
        self.assertEqual(c.url(top_ancestor=True), 'example_pkg/index.html#example_pkg.B')

        f = c.doc['overridden']
        self.assertEqual(f.url(), 'example_pkg/index.html#example_pkg.D.overridden')
        self.assertEqual(f.url(link_prefix='/'), '/example_pkg/index.html#example_pkg.D.overridden')
        self.assertEqual(f.url(relative_to=c.module), '#example_pkg.D.overridden')
        self.assertEqual(f.url(top_ancestor=1), 'example_pkg/index.html#example_pkg.B.overridden')
Exemple #18
0
    def test_inherits(self):
        module = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
        pdoc.link_inheritance()

        a = module.doc['A']
        b = module.doc['B']
        self.assertEqual(b.doc['inherited'].inherits, a.doc['inherited'])
        self.assertEqual(b.doc['overridden_same_docstring'].inherits,
                         a.doc['overridden_same_docstring'])
        self.assertEqual(b.doc['overridden'].inherits, None)

        c = module.doc['C']
        d = module.doc['D']
        self.assertEqual(d.doc['overridden'].inherits, c.doc['overridden'])
        self.assertEqual(c.doc['overridden'].inherits, b.doc['overridden'])
Exemple #19
0
    def test_qualname(self):
        module = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
        var = module.doc['var']
        cls = module.doc['B']
        nested_cls = cls.doc['C']
        cls_var = cls.doc['var']
        method = cls.doc['f']

        self.assertEqual(pdoc.External('foo').qualname, 'foo')
        self.assertEqual(module.qualname, EXAMPLE_MODULE)
        self.assertEqual(var.qualname, 'var')
        self.assertEqual(cls.qualname, 'B')
        self.assertEqual(nested_cls.qualname, 'B.C')
        self.assertEqual(cls_var.qualname, 'B.var')
        self.assertEqual(method.qualname, 'B.f')
Exemple #20
0
def documentation():
    choice = [(project.id, project.project_name)
              for project in Project.query.filter_by(
                  company_id=current_user.company_id)]
    form = UploadForm()
    form.projects.choices = choice
    if request.method == 'POST':
        if form.validate_on_submit():
            name = form.file.data.filename
            project_id = form.projects.data
            if not allowed_file(name):
                return render_template('error.html',
                                       message='Is this file python script?')
            form.file.data.save(os.path.join(os.path.abspath(''), 'review.py'))
            libpath = os.path.abspath('templates')
            project = Project.query.filter_by(id=project_id).first()
            try:
                mod = pdoc.import_module('review')
                doc = pdoc.Module(mod)
                html = doc.html()
            except Exception as e:
                print(e)
                return render_template(
                    'error.html',
                    user=current_user.user_username,
                    message='Something wrong in your module!')
            else:
                now = datetime.now()
                filename = str(uuid.uuid4())
                with open(os.path.join(libpath, f"{filename}.html"), "w") as f:
                    f.write(html)
                file = File(user_username=current_user.user_username,
                            project_id=project.id,
                            file_name=name,
                            upload_time=str(now),
                            documentation=filename)
                db.session.add(file)
                db.session.commit()
                return html
        return render_template('error.html',
                               message='Not valid form!',
                               user=current_user.user_username)
    return render_template('documentation.html',
                           user=current_user.user_username,
                           form=form)
Exemple #21
0
    def from_module_name(cls, name, base_path):
        module = pdoc.Module(pdoc.import_module(name), allsubmodules=True)
        methods = module.functions() + module.variables()
        examples = []

        if '__init__' in name:
            snippets = get_snippet_examples(
                name.split('.')[1], os.path.join(base_path, 'docs'))
            examples.extend(snippets)

        source_path = clean_source_path(module)

        return cls(module_id=name,
                   name=name.split('.')[-1].title(),
                   description=module.docstring,
                   examples=examples or [],
                   methods=[Method.from_pdoc(m) for m in methods],
                   source=source_path)
    def from_module_name(cls, name, base_path):
        module = pdoc.Module(pdoc.import_module(name), allsubmodules=True)
        methods = module.functions() + module.variables()
        examples = []

        if '__init__' in name:
            snippets = get_snippet_examples(name.split('.')[1],
                                            os.path.join(base_path, 'docs'))
            examples.extend(snippets)

        source_path = clean_source_path(module)

        return cls(module_id=name,
                   name=name.split('.')[-1].title(),
                   description=module.docstring,
                   examples=examples or [],
                   methods=[Method.from_pdoc(m) for m in methods],
                   source=source_path)
Exemple #23
0
def generate_module_docs(modules, docs_path, real_base_path, toc):
    for module_name in modules:
        module = Module.from_module_name(module_name, real_base_path)
        pdoc_module = pdoc.Module(pdoc.import_module(module_name),
                                  allsubmodules=True)
        for c in pdoc_module.classes():
            generate_class_docs(pdoc_module, c, docs_path, toc)

        module_path = (module_name.replace('.',
                                           '/').replace('__init__', 'index'))
        module_docs_path = os.path.join(docs_path, module_path) + '.json'

        if pdoc_module.functions():
            toc_key = module_name.replace('gcloud.', '').split('.')[0]
            toc_entry = build_toc_entry(module.name, module_path)
            toc['services'][toc_key].append(toc_entry)

        write_docs_file(module_docs_path,
                        json.dumps(module.to_dict(), indent=2, sort_keys=True))
Exemple #24
0
    def test_refname(self):
        mod = EXAMPLE_MODULE + '.' + 'subpkg'
        module = pdoc.Module(pdoc.import_module(mod))
        var = module.doc['var']
        cls = module.doc['B']
        nested_cls = cls.doc['C']
        cls_var = cls.doc['var']
        method = cls.doc['f']

        self.assertEqual(pdoc.External('foo').refname, 'foo')
        self.assertEqual(module.refname, mod)
        self.assertEqual(var.refname, mod + '.var')
        self.assertEqual(cls.refname, mod + '.B')
        self.assertEqual(nested_cls.refname, mod + '.B.C')
        self.assertEqual(cls_var.refname, mod + '.B.var')
        self.assertEqual(method.refname, mod + '.B.f')

        # Inherited method's refname points to class' implicit copy
        pdoc.link_inheritance()
        self.assertEqual(cls.doc['inherited'].refname, mod + '.B.inherited')
def generate_module_docs(modules, docs_path, real_base_path, toc):
    for module_name in modules:
        module = Module.from_module_name(module_name, real_base_path)
        pdoc_module = pdoc.Module(pdoc.import_module(module_name),
                                  allsubmodules=True)
        for c in pdoc_module.classes():
            generate_class_docs(pdoc_module, c, docs_path, toc)

        module_path = (module_name.replace('.', '/')
                       .replace('__init__', 'index'))
        module_docs_path = os.path.join(docs_path, module_path) + '.json'

        if pdoc_module.functions():
            toc_key = module_name.replace('google.cloud.', '').split('.')[0]
            toc_entry = build_toc_entry(module.name, module_path)
            toc['services'][toc_key].append(toc_entry)

        write_docs_file(module_docs_path,
                        json.dumps(module.to_dict(),
                                   indent=2, sort_keys=True))
Exemple #26
0
    def test__pdoc__dict(self):
        module = pdoc.import_module(EXAMPLE_MODULE)
        with patch.object(module, '__pdoc__', {'B': False}):
            mod = pdoc.Module(module)
            pdoc.link_inheritance()
            self.assertIn('A', mod.doc)
            self.assertNotIn('B', mod.doc)

        with patch.object(module, '__pdoc__', {'B.f': False}):
            mod = pdoc.Module(module)
            pdoc.link_inheritance()
            self.assertIn('B', mod.doc)
            self.assertNotIn('f', mod.doc['B'].doc)
            self.assertIsInstance(mod.find_ident('B.f'), pdoc.External)

        # GH-125: https://github.com/pdoc3/pdoc/issues/125
        with patch.object(module, '__pdoc__', {'B.inherited': False}):
            mod = pdoc.Module(module)
            pdoc.link_inheritance()
            self.assertNotIn('inherited', mod.doc['B'].doc)
Exemple #27
0
def documentation():
    if session.get('username'):
        form = UploadForm()
        if request.method == 'POST':
            if form.validate_on_submit():
                name = form.file.data.filename
                if allowed_file(name):
                    form.file.data.save(os.path.join(os.path.abspath(''), 'review.py'))
                    libpath = os.path.abspath('templates')
                    try:
                        mod = pdoc.import_module('review')
                        doc = pdoc.Module(mod)
                        html = doc.html()
                    except Exception as e:
                        print(e)
                        return render_template('error.html',
                                               user=session.get('username'),
                                               message='Something wrong in your module!')
                    else:
                        now = datetime.now()
                        user = User.query.filter_by(user_email=session.get('username')).first()
                        file = File(user_id=user.id,
                                    file_name=name,
                                    language_id=1,
                                    upload_time=str(now))
                        db.session.add(file)
                        filename = str(uuid.uuid4())
                        file = File.query.filter_by(user_id=user.id, file_name=name, upload_time=str(now)).first()
                        doc = Documentation(documentation_name=filename, file_id=file.id)
                        db.session.add(doc)
                        db.session.commit()
                        with open(os.path.join(libpath, f"{filename}.html"), "w") as f:
                            f.write(html)
                        return html
                return render_template('error.html', user=session.get('username'), message='Not valid file format!')
            return render_template('error.html', message='Not valid form!', user=session.get('username'))
        return render_template('documentation.html', user=session.get('username'), form=form)
    return render_template('notlogin.html', user=None)
Exemple #28
0
    def test_sorting(self):
        module = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))

        sorted_variables = module.variables()
        unsorted_variables = module.variables(sort=False)
        self.assertNotEqual(sorted_variables, unsorted_variables)
        self.assertEqual(sorted_variables, sorted(unsorted_variables))

        sorted_functions = module.functions()
        unsorted_functions = module.functions(sort=False)
        self.assertNotEqual(sorted_functions, unsorted_functions)
        self.assertEqual(sorted_functions, sorted(unsorted_functions))

        sorted_classes = module.classes()
        unsorted_classes = module.classes(sort=False)
        self.assertNotEqual(sorted_classes, unsorted_classes)
        self.assertEqual(sorted_classes, sorted(unsorted_classes))

        cls = module.doc["Docformats"]

        sorted_methods = cls.methods()
        unsorted_methods = cls.methods(sort=False)
        self.assertNotEqual(sorted_methods, unsorted_methods)
        self.assertEqual(sorted_methods, sorted(unsorted_methods))
Exemple #29
0
def main():
    if args.version:
        print(pdoc.__version__)
        sys.exit(0)

    # We close stdin because some modules, upon import, are not very polite
    # and block on stdin.
    try:
        sys.stdin.close()
    except:
        pass

    if not args.http and args.module_name is None:
        _eprint('No module name specified.')
        sys.exit(1)
    if args.template_dir is not None:
        pdoc.tpl_lookup.directories.insert(0, args.template_dir)
    if args.http:
        args.html = True
        args.external_links = True
        args.html_dir = args.http_dir
        args.overwrite = True
        args.link_prefix = '/'

    # If PYTHONPATH is set, let it override everything if we want it to.
    pypath = os.getenv('PYTHONPATH')
    if args.only_pypath and pypath is not None and len(pypath) > 0:
        pdoc.import_path = pypath.split(path.pathsep)

    if args.http:
        if args.module_name is not None:
            _eprint('Module names cannot be given with --http set.')
            sys.exit(1)

        # Run the HTTP server.
        httpd = HTTPServer((args.http_host, args.http_port), WebDoc)
        print('pdoc server ready at http://%s:%d'
              % (args.http_host, args.http_port), file=sys.stderr)

        httpd.serve_forever()
        httpd.server_close()
        sys.exit(0)

    docfilter = None
    if args.ident_name and len(args.ident_name.strip()) > 0:
        search = args.ident_name.strip()

        def docfilter(o):
            rname = o.refname
            if rname.find(search) > -1 or search.find(o.name) > -1:
                return True
            if isinstance(o, pdoc.Class):
                return search in o.doc or search in o.doc_init
            return False

    # Try to do a real import first. I think it's better to prefer
    # import paths over files. If a file is really necessary, then
    # specify the absolute path, which is guaranteed not to be a
    # Python import path.
    try:
        module = pdoc.import_module(args.module_name)
    except Exception as e:
        module = None

    # Get the module that we're documenting. Accommodate for import paths,
    # files and directories.
    if module is None:
        isdir = path.isdir(args.module_name)
        isfile = path.isfile(args.module_name)
        if isdir or isfile:
            fp = path.realpath(args.module_name)
            module_name = path.basename(fp)
            if isdir:
                fp = path.join(fp, '__init__.py')
            else:
                module_name, _ = path.splitext(module_name)

            # Use a special module name to avoid import conflicts.
            # It is hidden from view via the `Module` class.
            with open(fp) as f:
                module = imp.load_source('__pdoc_file_module__', fp, f)
                if isdir:
                    module.__path__ = [path.realpath(args.module_name)]
                module.__pdoc_module_name = module_name
        else:
            module = pdoc.import_module(args.module_name)
    module = pdoc.Module(module, docfilter=docfilter,
                         allsubmodules=args.all_submodules)

    # Plain text?
    if not args.html:
        output = module.text()
        try:
            print(output)
        except IOError as e:
            # This seems to happen for long documentation.
            # This is obviously a hack. What's the real cause? Dunno.
            if e.errno == 32:
                pass
            else:
                raise e
        sys.exit(0)

    # HTML output depends on whether the module being documented is a package
    # or not. If not, then output is written to {MODULE_NAME}.html in
    # `html-dir`. If it is a package, then a directory called {MODULE_NAME}
    # is created, and output is written to {MODULE_NAME}/index.html.
    # Submodules are written to {MODULE_NAME}/{MODULE_NAME}.m.html and
    # subpackages are written to {MODULE_NAME}/{MODULE_NAME}/index.html. And
    # so on... The same rules apply for `http_dir` when `pdoc` is run as an
    # HTTP server.
    if not args.http:
        quit_if_exists(module)
        html_out(module)
        sys.exit(0)
Exemple #30
0
        search = args.ident_name.strip()

        def docfilter(o):
            rname = o.refname
            if rname.find(search) > -1 or search.find(o.name) > -1:
                return True
            if isinstance(o, pdoc.Class):
                return search in o.doc or search in o.doc_init
            return False

    # Try to do a real import first. I think it's better to prefer
    # import paths over files. If a file is really necessary, then
    # specify the absolute path, which is guaranteed not to be a
    # Python import path.
    try:
        module = pdoc.import_module(args.module_name)
    except Exception as e:
        module = None

    # Get the module that we're documenting. Accommodate for import paths,
    # files and directories.
    if module is None:
        isdir = path.isdir(args.module_name)
        isfile = path.isfile(args.module_name)
        if isdir or isfile:
            fp = path.realpath(args.module_name)
            module_name = path.basename(fp)
            if isdir:
                fp = path.join(fp, '__init__.py')
            else:
                module_name, _ = path.splitext(module_name)
Exemple #31
0
 def test_imported_once(self):
     with chdir(os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE)):
         pdoc.import_module('_imported_once.py')
Exemple #32
0
 def test_import_filename(self):
     with patch.object(sys, 'path', ['']), \
             chdir(os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE)):
         pdoc.import_module('index')
Exemple #33
0
class Docformats(unittest.TestCase):
    _module = pdoc.Module(pdoc)
    _docmodule = pdoc.import_module(EXAMPLE_MODULE)

    @staticmethod
    def _link(dobj, *args, **kwargs):
        return '<a>`{}`</a>'.format(dobj.refname)

    def test_numpy(self):
        expected = '''<p>Summary line.</p>
<h2 id="parameters">Parameters</h2>
<dl>
<dt><strong><code>x1</code></strong>, <strong><code>x2</code></strong> :&ensp;<code>array_like</code></dt>
<dd>
<p>Input arrays,
description of <code>x1</code>, <code>x2</code>.</p>
<div class="admonition versionadded">
<p class="admonition-title">Added in version:&ensp;1.5.0</p>
</div>
</dd>
<dt><strong><code>x</code></strong> :&ensp;{ <code>NoneType</code>, <code>'B'</code>, <code>'C'</code> }, optional</dt>
<dd>&nbsp;</dd>
<dt><strong><code>n</code></strong> :&ensp;<code>int</code> or <code>list</code> of <code>int</code></dt>
<dd>Description of num</dd>
<dt><strong><code>*args</code></strong>, <strong><code>**kwargs</code></strong></dt>
<dd>Passed on.</dd>
</dl>
<h2 id="returns">Returns</h2>
<dl>
<dt><strong><code>output</code></strong> :&ensp;<a><code>pdoc.Doc</code></a></dt>
<dd>The output array</dd>
</dl>
<h2 id="raises">Raises</h2>
<dl>
<dt><strong><code>TypeError</code></strong></dt>
<dd>When something.</dd>
</dl>
<h2 id="see-also">See Also</h2>
<p><code>fromstring</code>, <code>loadtxt</code></p>
<h2 id="see-also_1">See Also</h2>
<dl>
<dt><a><code>pdoc.text</code></a></dt>
<dd>Function a with its description.</dd>
<dt><a><code>scipy.random.norm</code></a></dt>
<dd>Random variates, PDFs, etc.</dd>
</dl>
<h2 id="notes">Notes</h2>
<p>Foo bar.</p>
<h3 id="h3-title">H3 Title</h3>
<p>Foo bar.</p>'''  # noqa: E501
        text = inspect.getdoc(self._docmodule.numpy)
        html = to_html(text, module=self._module, link=self._link)
        self.assertEqual(html, expected)

    def test_google(self):
        expected = '''<p>Summary line.
Nomatch:</p>
<h2 id="args">Args</h2>
<dl>
<dt><strong><code>arg1</code></strong> :&ensp;<code>int</code></dt>
<dd>Description of arg1</dd>
<dt><strong><code>arg2</code></strong> :&ensp;<code>str</code> or <code>int</code></dt>
<dd>Description of arg2</dd>
<dt><strong><code>*args</code></strong></dt>
<dd>passed around</dd>
</dl>
<h2 id="returns">Returns</h2>
<dl>
<dt><strong><code>bool</code></strong></dt>
<dd>Description of return value</dd>
</dl>
<h2 id="raises">Raises</h2>
<dl>
<dt><strong><code>AttributeError</code></strong></dt>
<dd>
<p>The <code>Raises</code> section is a list of all exceptions
that are relevant to the interface.</p>
<p>and a third line.</p>
</dd>
<dt><strong><code>ValueError</code></strong></dt>
<dd>If <code>arg2</code> is equal to <code>arg1</code>.</dd>
</dl>
<h2 id="examples">Examples</h2>
<p>Examples in doctest format.</p>
<pre><code>&gt;&gt;&gt; a = [1,2,3]
</code></pre>
<h2 id="todos">Todos</h2>
<ul>
<li>For module TODOs</li>
</ul>'''
        text = inspect.getdoc(self._docmodule.google)
        html = to_html(text, module=self._module, link=self._link)
        self.assertEqual(html, expected)

    def test_doctests(self):
        expected = '''<p>Need an intro paragrapgh.</p>
<pre><code>&gt;&gt;&gt; Then code is indented one level
</code></pre>
<p>Alternatively</p>
<pre><code>fenced code works
</code></pre>'''
        text = inspect.getdoc(self._docmodule.doctests)
        html = to_html(text, module=self._module, link=self._link)
        self.assertEqual(html, expected)

    def test_reST_directives(self):
        expected = '''<div class="admonition todo">
<p class="admonition-title">TODO</p>
<p>Create something.</p>
</div>
<div class="admonition admonition">
<p class="admonition-title">Example</p>
<p>Image shows something.</p>
<p><img alt="" src="/logo.png"></p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Can only nest admonitions two levels.</p>
</div>
</div>
<p><img alt="" src="https://www.debian.org/logos/openlogo-nd-100.png"></p>
<p>Now you know.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Some warning
lines.</p>
</div>
<ul>
<li>
<p>Describe some func in a list
  across multiple lines:</p>
<div class="admonition deprecated">
<p class="admonition-title">Deprecated since version:&ensp;3.1</p>
<p>Use <code>spam</code> instead.</p>
</div>
<div class="admonition versionadded">
<p class="admonition-title">Added in version:&ensp;2.5</p>
<p>The <em>spam</em> parameter.</p>
</div>
</li>
</ul>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p>Don't touch this!</p>
</div>'''
        text = inspect.getdoc(self._docmodule.reST_directives)
        html = to_html(text, module=self._module, link=self._link)
        self.assertEqual(html, expected)
Exemple #34
0
 def test__pdoc__invalid_value(self):
     module = pdoc.import_module(EXAMPLE_MODULE)
     with patch.object(module, '__pdoc__', {'B': 1}), \
             self.assertRaises(ValueError):
         pdoc.Module(module)
         pdoc.link_inheritance()
Exemple #35
0
 def setUpClass(cls):
     cls._module = pdoc.Module(pdoc)
     cls._docmodule = pdoc.import_module(EXAMPLE_MODULE)
Exemple #36
0
used = {}

for subdir, dirs, files in os.walk('.'):
	for file in files:
		if file.endswith('.py'): 
			program = file.split('.py')[0]
			if program in used: continue
			used[program] = 1
			
progress = [0,0]

for program in used.keys():
	print("Documenting",program+"...")
	try:
		mod = pdoc.Module(pdoc.import_module(program))
		doc = open("docs/"+program+".html",'w')

		writ = mod.html()
		doc.write(writ)

		doc.close()
		print("Documented",program)
		progress[0] += 1
	except (ImportError, SyntaxError,AttributeError) as e:
		print("Failed to document",program,e)
		progress[1] += 1
		
print("Documented",progress[0],'files')
print("Failed on",progress[1],'files')