best practices for GitHub pages?

[cs01]

GitHub pages are a common way to host documentation for sites. They require one of the following to host in source code:

• master branch /docs folder
• master branch
• gh-pages branch

Right now I'm using master branch /docs for pygdbmi, and I have what I would assume is a very common project structure, yet my workflow has a little hack in it. I generate my docs with the following make recipe:

docs:
	pdoc --html  --force --output-dir docs pygdbmi
	mv docs/pygdbmi/* docs
	rmdir docs/pygdbmi

Is there a way to generate docs directly to the --output-dir? By namespacing it with the package name, it breaks it for GitHub pages.

[kernc]

What's wrong with invoking mv as above?

[kernc]

pdoc CLI usage allows for more than one module/package specified:

pdoc --html mypackage1 mypackage2 ...

1. Are functions returning Union[T, List[T]] really such a good idea?

[kernc]

Generating all modules/packages to a single landing page at index.html (that then point to package_1/index.html, package_2/index.html)

Then you'd have another doorway page (like the --http one) exhibiting a single link to your project documentation. Would you like that (i.e. leave it in docs dir as is, without moving)?

Disallowing multiple projects to have docs generated at once

No. Specifying multiple projects is the mechanism by which you make pdoc aware of, and thereby link to, symbols in disjunct packages.

---

The problem with 1. is that subsequent runs are not deterministically idempotent.

$ pdoc --html -o docs project1

# Creates a different filesystem hierarchy.
# Doesn't reliably warn for overwriting project1.
# Leaves docs/index.html to remain stale and misleading.
$ pdoc --html -o docs project1 project2

This idea also won't work because it would break existing CI / deployments.

[kernc]

I'm not convinced that running mv, explicitly, hopefully scripted, represents a hassle.

Let's maybe leave this open for a while and see how many votes it accrues.

[florimondmanca]

Hey! I'm interested in pdoc, but my use case is that of generating pages and integrating those within another generated documentation, so I won't be deploying the output of pdoc to GitHub Pages directly.

All that said, I totally agree that at least documenting a typical workflow for GitHub pages would be a nice extra.

[KyleKing]

FWIW, I have a DoIt script in Python that does some filesystem manipulation to ouput documentation to gh-pages. Would love feedback if there is a better to do this

Process:

1. Run pdoc
2. copy pdoc output to dash_charts-gh-pages/
3. Commit dash_charts-gh-pages/

Directory Structure:

• parent_dir/
  • dash_charts-master/
  • dash_charts-gh-pages/

Code:

See task_document and task_commit_docs from https://github.com/KyleKing/dash_charts/blob/master/dodo.py (note: also moves a directory with example Python code temporarily into module so they appear in the documentation, but isn't necessary)

Result: https://kyleking.me/dash_charts/