List generated files on --html

[epogrebnyak]

Starting to use pdoc3, great package, fast access to documentation.

A suggestion about README.md. The Usage section just mentions the inputs and no outputs:

Pdoc will accept a Python module file, package directory or an import path.

It would have helped me to learn from usage section that by default pdoc3 will save generated documentation to html/<package_name> folder. A user feels rather confused about not knowing what the program did.

Maybe can also add a message "Saved documentation to " as console ouput.

I can do a PR, if needed.

[kernc]

Maybe can also add a message "Saved documentation to " as console ouput.

Been thinking about this for a long while! A printed list of generated files certainly sounds practical. 👍

[kernc]

Maybe a note on --output-dir in help for --html? Feel free to revise.

[epogrebnyak]

Maybe a note on --output-dir in help for --html? Feel free to revise.

That message helps, but I think in the documentation one needs to learn about the behaviour earlier to be able to run the first example quickly and be confident to know where is the output.

[epogrebnyak]

Maybe can also add a message "Saved documentation to " as console ouput.

Been thinking about this for a long while! A printed list of generated files certainly sounds practical. 👍

Something in line of below?

Generated files:
d:\github\boo\docs\boo\columns.html
d:\github\boo\docs\boo\curl.html
d:\github\boo\docs\boo\errors.html
d:\github\boo\docs\boo\file.html
d:\github\boo\docs\boo\helper.html
d:\github\boo\docs\boo\index.html
d:\github\boo\docs\boo\main.html
d:\github\boo\docs\boo\okved.html
d:\github\boo\docs\boo\path.html
d:\github\boo\docs\boo\whatis.html
d:\github\boo\docs\boo\year.html

Would really help a new user! Let me consider how to implement for you with PR (print() is the easiest, but not the cleanest)

[kernc]

This further gives one the ability of quick review. 👍

And is useful in CLI sense. Look at the surrounding code, I think print() is used already.
Maybe redirect "Generated files:" to sys.stderr instead of stdout, this will make it universally composable (piped into xargs, etc.).

[epogrebnyak]

Looks like we can achieve listing of files with a single print(f) in recursive_write_files, seems a bit too easy.

[kernc]

But that seems perfect! 😁

There is no more elaborate logging currently in place, and printing just filenames can indeed be further used in scripting.

[epogrebnyak]

Sending a PR with this:

https://github.com/epogrebnyak/pdoc/blob/1bcde4dfe32f9aea43b2b63928acfb2ebffb3d54/pdoc/cli.py#L319-L325

[epogrebnyak]

Couple observations - later in code we use sys.stdout.write, which is similar to print():

pdoc/pdoc/cli.py

Lines 497 to 500 in 5d15e61

	else:
	sys.stdout.write(module.text(**template_config))
	# Two blank lines between two modules' texts
	sys.stdout.write(os.linesep * (1 + 2 * int(module != modules[-1])))

Is there a special reason to use sys.stdout.write? Maybe change it to print() for consistency?
It took a while for me to htink over why this case is different from print and I could not think of a good answer.

[kernc]

print(..., end='\n') auto-appends a newline, file.write() writes literally.

I had to check myself. 😆

[epogrebnyak]

Also a more general note - for Github the ideal example is pdoc --html -o docs mypackage, which produces documentation ready to be published for Github Pages. I think it is a strong usercase.

Currently pdoc --html -o docs mypackage will create documentation in docs/mypackage, not docs. This is a bit surprising, and to move documentation from docs/mypackage to docs, one needs an extra move command.

Two ideas:

• change the behavior of -o switch (but that breaks your API)
• add -O or some other switch that writes exactly to specified output_directory directory, not output_directory/package

[epogrebnyak]

print(..., end='\n') auto-appends a newline, file.write() writes literally.

I had to check myself. 😆

That numbering of newlines looks like serious stuff: os.linesep * (1 + 2 * int(module != modules[-1])) :)

I understand now why you need write (), was not clear from start.

[kernc]

That numbering of newlines looks like serious stuff: os.linesep * (1 + 2 * int(module != modules[-1])) :)

Welcome to be as brief more clearly. 😛

Also a more general note - for Github the ideal example is pdoc --html -o docs mypackage, which produces documentation ready to be published for Github Pages. I think it is a strong usercase.

Discussed with some ideas and workarounds in #55.