best practices for GitHub pages?

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.

What's wrong with invoking mv as above?

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

pdoc --html mypackage1 mypackage2 ...

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

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.

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.

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.

Minor documentation build process fixes and develop dependency updates (

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:

Run pdoc
copy pdoc output to dash_charts-gh-pages/
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/

I have based the documentation for my project on the Cayman theme, but modified it quite a bit to fit my needs. The API reference (which is still very much work in progress) is generated by pdoc and checked in statically. To integrate it with Cayman, I modified the template to include some front matter. This also allows me to change permalink to get rid of the .html extension, so that it integrates nicely. Also had to do some other minor tweaks, e.g. fix CSS.

Generating the output is done with a small python hack I did, which also contains a "verify" action that checks if the reference is up-to-date with code and fails otherwise. The "verify" step is run by tox (and in turn GitHub Actions), so it's not possible to merge anything if the documentation is "old".

Some links for inspiration:

The documentation can be seen at at pyatv.dev/api
Templates for pdoc is here
Script to generate API documentation is here (integration with tox here)

Not in any way a perfect solution, but works pretty good for my needs. Maybe it serves as inspiration for someone else. 🍰

I have a simple redirect at docs/index.html that contains:

<meta http-equiv="refresh" content="0; url=./{{project-name}}/" />

where one should obviously replace {{project-name}} with their project name. This way I can generate my documentation directly with using the -o docs flag and simply commit the changes.

A more performant line suggested by kernc:

<link rel="preload prerender" as="document" href="./{{project-name}}/">

New: initialize index.html as redirect

Move docs to docs folder and add redirect index as suggested on pdoc3…

update docs using link redirect as per pdoc3/pdoc#55 (comment)

I have a simple redirect at docs/index.html that contains:
<meta http-equiv="refresh" content="0; url=./{{project-name}}/" />
where one should obviously replace {{project-name}} with their project name. This way I can generate my documentation directly with using the -o docs flag and simply commit the changes.

Just for n00bs like me, this looks like a file called index.html with the following content:

<!DOCTYPE html>
<html>

<head>
    <meta http-equiv="refresh" content="0; url=./{{project-name}}/" />
</head>

</html>

Trying some pdoc templates I found

Navigation Menu

Repository navigation

best practices for GitHub pages? #55

13 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

best practices for GitHub pages? #55

Description

Activity

kernc commented on Apr 30, 2019

kernc commented on Apr 30, 2019

kernc commented on Apr 30, 2019

kernc commented on Apr 30, 2019

florimondmanca commented on Apr 30, 2019

KyleKing commented on Feb 15, 2020

postlund commented on Mar 30, 2020

rirze commented on Apr 15, 2020

13 remaining items

kernc commented on May 13, 2020

rirze commented on May 13, 2020

epogrebnyak commented on May 13, 2020

kernc commented on May 13, 2020

epogrebnyak commented on May 13, 2020

kernc commented on May 13, 2020

rirze commented on May 13, 2020

ethanabrooks commented on Mar 27, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions