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

[Docs][CI] Ensure docfx links stay valid, prepare future xml API docs options, keep docs simple maintainable and introduce CI integration for this

Aperta
  • Qualcosa non va?
#846 6 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
Funzionalità
Chiarezza
Da chiarire
Stato di attività
Ferma
Stack tecnologico
csharp, github-actions
Ambito
build-system, ci-cd, documentation

Direzione di ricerca

Inizia esaminando docfx.json, commitlint.yml, i workflow GitHub Actions esistenti e la issue correlata #845. La issue contiene diversi approcci possibili per CI, branch, labeling e documentazione API, senza un ambito definito. Per considerare il lavoro completato sarebbero necessari un design concordato e una validazione funzionante che garantisca che i link nella documentazione generata rimangano validi.

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

Descrizione

docs improvement

This Docs/CI Enhancement targets to keep pre / development Branch Docs + Releases API:

  • cleanly seperated on their branch (intellisense/markdown suggestion support)
  • allow valid API docs and source code linking in docs

[!IMPORTANT]
docfx docs generation will fail completly or produce invalid Links if we include the metadata step on a branch that doesn't include the to be linked file or src code!

To Ensure the latest docs PR (find linked in Additional Information Section) will not fall on our toes in the future or cause unnessesary additional (automate-able) work for us, we should consider:

  • GH Action for PR's md docs changes: If there are only md docs changes (our current build not includes API docs) This should get triggered and add a PR for maybe cherry picking those commits from development onto master? but this will potentially be causing invalid links as soon as we step on to use API docs!

  • Enhance/Ensure proper Commit Labels: We should then explicitly keep our commits cleanly seperated and scoped/categorized properly, which would include such relevant changes. It's possible for the commitlint.yml from what I readed by now, to add more allowed labels or similar but we should have this discussed and decided properly, what we want and maybe find ways to do this, which I maybe did possibly not consider here.

  • GH Action: Ensure DocFx correct build for API metadata: Pay Attention as soon as we might want to use generate xml docs from any source code via metadata!
    Produce and add API Docs after changes on non-master-merge PR branches:

    • create the API them in this case after their source branch got a relevant PR merge
    • have all docfx docs produced and merged to master (?) or @andrerav what do you think of reusing the gh-pages branch for our docs product then 🤔 ? possibly this is the cleanest way...

  • Review & Add DocFx Content Setup for API version support:

    I havn't been successfull by now with the output / dest settings in docfx.json which are linted as depreciated but I see many others still use them and I think this is required to have a proper xml API output control for this 🤔

    • Possibly I will need to ask the docfx team for help, to come to a working setup, but my targeted idea would be something like this in our github.io web docs then:

      image

Additional Information

  • #845
    @DocSvartz @stagep @andrerav
Lingua principale
C#
Stelle
5.2k
Fork
411
Merge medio
1g 8h
PR unite (30g)
4

Preparare l'ambiente

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 MapsterMapper/Mapster

Tutte le issue di MapsterMapper/Mapster

Issue simili

Altre issue su C#

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.