plotly / plotly/Plotly.NET

Move official docs page to this repo and update accordingly

Offen
#376 0 Kommentare 3 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Area: Documentation Area: Meta
Vorherrschende Sprache
F#
Sterne
860
Forks
99
Ø Merge
22 Min.
Gemergte PRs (30 T.)
1

Beschreibung

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.

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne damit, die aktuelle fsdocs-Einrichtung in diesem Repository mit den offiziellen Inhalten und der offiziellen Pipeline in plotly.net-docs zu vergleichen, und prüfe documentation/issues/1696 sowie die Issues #353 und #356 auf Einschränkungen. Die Aufgabe ist erledigt, wenn die offizielle Pipeline Tutorial-Inhalte aus diesem Repository verwendet, von fsdocs generierte API-Dokumentation veröffentlicht und nicht mehr auf ein separates Tutorials-Repository oder den fsdocs-Tutorial-Build angewiesen ist.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
fsharp
Bereich
build-system, documentation
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.