Docs site is pushed to gh-pages but GitHub Pages is not enabled; README's API reference link shows raw ::: directives

Aperta
#109 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
55/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
python

Direzione di ricerca

Read .github/workflows/documentation.yml, mkdocs.yml, and the README links in README.md:58-66; compare the setup with the datacache example mentioned in the issue. Check how the gh-pages branch is configured and how MkDocs reference pages are published. Done means the documentation site resolves and the README API reference displays rendered signatures and parameters.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Problem

On every push to master, the Documentation workflow builds the MkDocs site and pushes it to gh-pages with ghp-import. The repository doesn't serve that branch, though: GitHub Pages isn't enabled for gtfparse. So the site that mkdocs.yml declares (site_url: https://openvax.github.io/gtfparse/) returns 404. datacache and pyensembl use the same workflow, and their sites do resolve.

Because the site isn't served, the README links to the raw Markdown files on GitHub instead. For the guides that works. For the API reference it doesn't: docs/reference.md is a task table followed by eight mkdocstrings directives (::: gtfparse.read_gtf, ...). GitHub shows those as literal text. The README's "API reference for every public function" link therefore leads to a page with no signatures or parameters.

Evidence

Read at f886f1e, checked 2026-11-07:

  • .github/workflows/documentation.yml:23-41: the publish job runs ghp-import --no-jekyll --push --force site/. The latest run, 42082284253, shows build success, publish success. The gh-pages branch was last updated 2026-11-05.
  • gh api repos/openvax/gtfparse/pages returns 404 Not Found. https://openvax.github.io/gtfparse/ returns 404. For comparison, gh api repos/openvax/datacache/pages reports source gh-pages, and https://openvax.github.io/datacache/ and https://openvax.github.io/pyensembl/ return 200.
  • mkdocs.yml:3: site_url: https://openvax.github.io/gtfparse/. It was added with the workflow in 0191ffc (2026-10-06).
  • README.md:58-66: the documentation links point to github.com/openvax/gtfparse/blob/master/docs/..., including docs/reference.md.
  • docs/reference.md:17-31: the ::: directives.

Suggested fix

Enable GitHub Pages for the repository from the gh-pages branch, as datacache does. Then point the README's documentation links at https://openvax.github.io/gtfparse/ and its pages, as datacache's README does. If the site isn't wanted, delete the publish job and site_url, and give docs/reference.md content that reads on GitHub.

https://claude.ai/code/session_01JHJhwj29oDqoeu7TYd34Pi

Lingua principale
Python
Stelle
130
Fork
34
Merge medio
23h 45m
PR unite (30g)
9

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di openvax/gtfparse

Tutte le issue di openvax/gtfparse

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.