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?

[cs01]

Every person that uses pdoc with GitHub pages has to encounter the problem, think of a workaround, then write the workaround. It's not a huge deal, but eliminating as many of those little things as possible adds up to a better developer experience, which leads to more adoption of pdoc. (Sphinx has so many of these it drove me to look for a better tool, and here I am at pdoc 😄 )

For example, mkdocs has an amazing DX where you just run

mkdocs gh-deploy

>> mkdocs gh-deploy -h
Usage: mkdocs gh-deploy [OPTIONS]

  Deploy your documentation to GitHub Pages

Options:
  -c, --clean / --dirty       Remove old files from the site_dir before
                              building (the default).
  -f, --config-file FILENAME  Provide a specific MkDocs config
  -m, --message TEXT          A commit message to use when committing to the
                              Github Pages remote branch. Commit {sha} and
                              MkDocs {version} are available as expansions
  -b, --remote-branch TEXT    The remote branch to commit to for Github Pages.
                              This overrides the value specified in config
  -r, --remote-name TEXT      The remote name to commit to for Github Pages.
                              This overrides the value specified in config
  --force                     Force the push to the repository.
  --ignore-version            Ignore check that build is not being deployed
                              with an older version of MkDocs.
  -q, --quiet                 Silence warnings
  -v, --verbose               Enable verbose output
  -h, --help                  Show this message and exit.

[kernc]

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

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

[cs01]

What do you think of either

• Generating all modules/packages to a single landing page at index.html
  (that then point to package_1/index.html, package_2/index.html)
• Disallowing multiple projects to have docs generated at once

[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.

[cs01]

Before we go too far down the implementation route, I would like to ask whether you think publishing docs to GitHub pages is a workflow a large percentage of users will be interested in doing, and is therefore valuable for pdoc to optimize for?

[kernc]

True. I'm personally not convinced that running mv, explicit, hopefully scripted, represents a hassle.

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

[cs01]

Sounds good. In the mean time I can add something to the docs describing this workflow.

[cs01]

Add a thumbs up to this comment if building easier GitHub page workflows in pdoc is important to you 👍 .

[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.