Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Are API docs needed for this repo?

Aperta
  • Qualcosa non va?
#10 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Documentazione
Chiarezza
Da chiarire
Stato di attività
Ferma
Stack tecnologico
python
Ambito
documentation

Direzione di ricerca

Inizia leggendo docs/sphinx-build.sh, .github/workflows/httomo_backends_docs.yml e docs/index.rst per tracciare come viene generato e pubblicato l’output dell’API. Esamina gli script sotto httomo_backends/ e la issue di httomo referenziata prima di decidere se la documentazione dell’API debba appartenere a questo progetto. Il lavoro è completato quando il repository ha un ambito concordato per la documentazione dell’API e la relativa configurazione di build e indice riflette coerentemente tale decisione.

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

Descrizione

documentation question

There's API docs being generated in the sphinx-build.sh script: https://github.com/DiamondLightSource/httomo-backends/blob/a34bf5802fc541ef5a0c541377b000ce596882aa/docs/sphinx-build.sh#L27-L28

and similarly in the CI: https://github.com/DiamondLightSource/httomo-backends/blob/a34bf5802fc541ef5a0c541377b000ce596882aa/.github/workflows/httomo_backends_docs.yml#L34-L35

but the output rst files from this aren't being included in index.rst (so the API docs aren't included in the final docs deployment).

So that's one reason why I'm questioning if API docs are needed for this repo, because they're being built but not being used in the final docs deployment.

Another reason is if this repo needs API docs. At the moment, there's a handful of scripts used for generating the YAML templates, and that's it. The httomo_backends/ dir isn't even a python package (there's no __init__.py file), so there's no python modules in this repo really, just some scripts for generating YAML templates.

One question is: do we need/want API docs for the handful of scripts currently here?

Another question: for stuff that gets moved to httomo-backends (such as memory estimators and padding calculators from httomo, see https://github.com/DiamondLightSource/httomo/issues/429), would we like API docs for those? At the moment in httomo, memory estimators are private functions where they reside, but I imagine that when they get moved into httomo-backends they'll be made public functions - which may make sense to have API docs as they're public, but may also not make sense to have API docs, because they all have the same interface (parameters), and their usage is made obvious by how they are used in httomo. In which case, perhaps API docs in httomo-backends isn't really needed, but rather, general documentation on how the memory estimator and padding calculator functions are used in httomo/how they hook into httomo.

Lingua principale
Python
Stelle
0
Fork
1
Nessuna PR unita negli ultimi 30g

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 DiamondLightSource/httomo-backends

Tutte le issue di DiamondLightSource/httomo-backends

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.