plotly / plotly/Plotly.NET

Move official docs page to this repo and update accordingly

Aperta
#376 0 commenti 3 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Area: Documentation Area: Meta
Lingua principale
F#
Stelle
860
Fork
99
Merge medio
22m
PR unite (30g)
1

Descrizione

Currently, there are 2 sets of docs for this library:

  • docs hosted on https://plotly.net, which i will call internal in this issue:

    • built in this repo using fsdocs
    • contains tutorials rendered from .fsx files and api docs created by fsdocs via assembly inspection
    • are up-to-date with the currently version of the library
    • almost exclusively F# content (meaning C# users need to put in a little effort translating the code samples)
  • docs hosted on https://plotly.com/fsharp and https://plotly.com/csharp , which i will call official in this issue

There is understandably quite some confusion about this (see #353 and #356), with users coming from the official docs reporting issues that are long fixed in recent versions. In addition to that, providing high-quality C# docs is hard with fsdocs, which mainly focuses on creating F# content with F# tooling.

Since official docs most likely have way better SEO than the internal one, this problem will only increase with time, meaning we should move to only hosting the official docs.

So the following should be done imo:

  • change the doc build pipeline to use content in this repo instead of https://github.com/plotly/plotly.net-docs, since i do not want to maintain two separate repos for this. Python , JS, and R versions of plotly do it that way as well.
  • use the api docs output from fsdocs, similarily to what the python lib is doing
  • ditch fsdocs for the tutorials in favor of the official docs build pipeline.

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

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.

Direzione di ricerca

Inizia confrontando la configurazione attuale di fsdocs in questo repository con i contenuti e la pipeline ufficiali di plotly.net-docs, e consulta documentation/issues/1696 e le issues #353 e #356 per verificare i vincoli. Il lavoro è completo quando la pipeline ufficiale utilizza i contenuti dei tutorial di questo repository, pubblica la documentazione API generata da fsdocs e non dipende più da un repository separato per i tutorial né dalla build dei tutorial di fsdocs.

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

Valutazione

Stack tecnologico
fsharp
Ambito
build-system, documentation
Tipo di issue
Funzionalità
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.