pdoc3 does not generate html output

[laimaretto]

Expected Behavior

As per the information in here I was expecting the documentation to be placed inside the html folder.

Actual Behavior

Is not happening.

Steps to Reproduce

1. sudo pip3 install pdoc3
2. cd /myProject
3. pdoc3 --html -o ./html/ myProg.pu

Additional info

• pdoc version:
  pip3 show pdoc3
  Name: pdoc3
  Version: 0.9.2
  Summary: Auto-generate API documentation for Python projects.
  Home-page: https://pdoc3.github.io/pdoc/
  Author: UNKNOWN
  Author-email: UNKNOWN
  License: AGPL-3.0
  Location: /usr/local/lib/python3.5/dist-packages
  Requires: markdown, mako
  Required-by:

[kernc]

What is happening instead? Standard output, error?

[laimaretto]

Nothing. No error. My program just runs and that's it. My program is called get_config.py.

lucas@VMserver16:~/gen_config$ pdoc3 --html -o html/ get_config.py
/home/lucas/gen_config/config/out.cfg
lucas@VMserver16:~/gen_config$ 
lucas@VMserver16:~/gen_config$ ls html/ -l
total 0
lucas@VMserver16:~/gen_config$

[kernc]

Interesting. Instead, this should be happening:

pdoc/pdoc/cli.py

Lines 532 to 535 in 49b7773

	modules = [pdoc.Module(module, docfilter=docfilter,
	skip_errors=args.skip_errors)
	for module in args.modules]
	pdoc.link_inheritance()

pdoc/pdoc/cli.py

Lines 570 to 573 in 49b7773

	for module in modules:
	if args.html:
	_quit_if_exists(module, ext='.html')
	recursive_write_files(module, ext='.html', **template_config)

What does this return?

mod = pdoc.Module('get_config.py')
mod.html()

There's way too little for me to go by there (cd yourProject is not that reproducible), so welcome to investigate.

[laimaretto]

Ok, so if I run it that way, I do get an exception...

In [1]: import pdoc                                                                                                                                                                                                

In [2]: mod = pdoc.Module('get_config.py')                                                                                                                                                                         
/home/lucas/gen_config/config/out.cfg
An exception has occurred, use %tb to see the full traceback.

SystemExit: 0

/usr/local/lib/python3.5/dist-packages/IPython/core/interactiveshell.py:3334: UserWarning: To exit: use 'exit', 'quit', or Ctrl-D.
  warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)

If I run it using %tb I get more information...

In [6]: mod = pdoc.Module('get_config.py') %tb                                                                                                                                                                     
---------------------------------------------------------------------------
ImportError                               Traceback (most recent call last)
/usr/local/lib/python3.5/dist-packages/pdoc/__init__.py in import_module(module, reload)
    224             try:
--> 225                 module = importlib.import_module(module_path)
    226             except Exception as e:

/usr/lib/python3.5/importlib/__init__.py in import_module(name, package)
    125             level += 1
--> 126     return _bootstrap._gcd_import(name[level:], package, level)
    127 

/usr/lib/python3.5/importlib/_bootstrap.py in _gcd_import(name, package, level)

/usr/lib/python3.5/importlib/_bootstrap.py in _find_and_load(name, import_)

/usr/lib/python3.5/importlib/_bootstrap.py in _find_and_load_unlocked(name, import_)

/usr/lib/python3.5/importlib/_bootstrap.py in _call_with_frames_removed(f, *args, **kwds)

/usr/lib/python3.5/importlib/_bootstrap.py in _gcd_import(name, package, level)

/usr/lib/python3.5/importlib/_bootstrap.py in _find_and_load(name, import_)

/usr/lib/python3.5/importlib/_bootstrap.py in _find_and_load_unlocked(name, import_)

ImportError: No module named 'get_config'

During handling of the above exception, another exception occurred:

ImportError                               Traceback (most recent call last)
<ipython-input-6-ebdbd9b636b3> in <module>
----> 1 mod = pdoc.Module('get_config.py') %tb

/usr/local/lib/python3.5/dist-packages/pdoc/__init__.py in __init__(self, module, docfilter, supermodule, context, skip_errors)
    607         """
    608         if isinstance(module, str):
--> 609             module = import_module(module)
    610 
    611         super().__init__(module.__name__, self, module)

/usr/local/lib/python3.5/dist-packages/pdoc/__init__.py in import_module(module, reload)
    226             except Exception as e:
    227                 raise ImportError('Error importing {!r}: {}: {}'
--> 228                                   .format(module, e.__class__.__name__, e))
    229 
    230     assert inspect.ismodule(module)

ImportError: Error importing 'get_config.py': ImportError: No module named 'get_config'

So I wonder if there are some requirements inside the .py for pdoc to work?

Thanks!

[kernc]

Maybe try absolute instead of relative path. Printed /home/lucas/gen_config/config/out.cfg rather indicates that get_config.py is, in fact, imported and executed, is that correct?

[laimaretto]

So, I've tried as suggested the absolute path, not working either, both on the CLI or within the Python interpreter ... :-(

1. CLI

lucas@VMserver16:~/gen_config$ pdoc3 --html -o html/ /home/lucas/gen_config/get_config.py
/home/lucas/gen_config/config/out.cfg
lucas@VMserver16:~/gen_config$ 
lucas@VMserver16:~/gen_config$ ls html/ -l
total 0
lucas@VMserver16:~/gen_config$ 

2. Interpreter

In [3]: import pdoc                                                                                                                                                                                                

In [4]: mod = pdoc.Module('/home/lucas/gen_config/get_config.py')                                                                                                                                    
/home/lucas/gen_config/config/out.cfg
An exception has occurred, use %tb to see the full traceback.

SystemExit: 0

---*---
Now, regarding your other question, get_config.py is just a little program that connects to a MySQL DB, gathers some info, and produces a configuration file out.cfg for a networking device. The path where the config file is located is shown at the end /home/lucas/gen_config/config/out.cfg. So, I believe the answer is no: get_config.py is not imported, I just execute it on the CLI.

lucas@VMserver16:~/gen_config$ python3 get_config.py 
/home/lucas/gen_config/config/out.cfg

What it is true, is that I do import some libraries from within get_config.py... would it a problem?

[kernc]

I don't know whether it's a problem. You should use a main guard for runnable code.

In [4]: mod = pdoc.Module('/home/lucas/gen_config/get_config.py')
/home/lucas/gen_config/config/out.cfg

SystemExit: 0

The fact that config line is printed out indicates the module is "run". That SystemExit is not pdoc's doing.

[laimaretto]

Indeed, now that you mention it, the SystemExit: 0 is in my program.

if fnc_aux_test_config_file(var_config_file) == -1:
	# do some stuff
	sys.exit(1)
else:
	# Everything ok, writing files ...
	fnc_aux_write_config(var_config_file)
	sys.exit(0)

I do the previous because depending on the sys.exit() I can use that later on.

On the other hand, I don't know what you mean with 'the module is "run" ...'... :-P

Finally, I'll have a look a the suggestion of the main guard: I don't have a main guard in my code ... may be that will do it ...

thanks !

[laimaretto]

Ok, I confirm that adding a main guard, at least produces an output. Thanks for the hint!

However, the render of the HTML file, seems a little incomplete. Let me share a snippet of my code so may be you'll understand.

1. I do some imports at the very beginning, with system imports and also some imports of my own... after that I have declared a function in the get_config.py file, which is my main file ...

import MySQLdb
import sys
import yaml
import pandas as pd

from templates.csr.csr import *

def fnc_sql_cfgTmplt(var_obj_id):
	"""Function that implements an SQL query towards DB"""
        return smthn.

2. The main guard: as you see, in the main section, I do call the previously declared function fnc_sql_cfgTmplt() but also a function called fnc_sql_build_query1() which is declared within my local imports templates.csr.csr.

if __name__ == '__main__':

	cfgTemplate = pd.read_sql(fnc_sql_cfgTmplt(var_obj_id), con = db)

	var_ports  = pd.read_sql(fnc_sql_build_query1(var_obj_id), con = db)
	db.close()

Well, in the produced HTML by pdoc, the only function that I can see is fnc_sql_cfgTmplt() which is the one declared inside get_config.py; none of the functions inside templates.csr.csr are shown ...
The same happens with other several functions that I use in my main file get_config.py which are declared inside templates.csr.csr: they are not shown inside the HTML file ...

Any ideas? :-P ... thank you very much for your patience ... :-)

[kernc]

Docs hierarchy follows module hierarchy is one of the imperatives. With pdoc ... get_config.py you're only telling it to document the one module. Point it at the parent package/directory to document all modules instead.

[laimaretto]

oh! I see ... brilliant ... :-) ... now it works ...pdoc3 --html -o docs/doc.html . did the job ...

thank you very much ... !