Wie Markdown und Dokument

Dokumentieren Sie Ihre Arbeit¶

Leonardo Da Vinci benutzte Zeitschriften, um seine Ideen zu skizzieren, zu entwickeln und schließlich weiterzugeben. Alexander von Humboldt dokumentierte viele seiner Reisen in Reisezeitschriften und Marie Skłodowska Curie schrieb die Theorie der “Radioaktivität” mit Stiften und Papieren. Heute haben sich Schreibmedien zu unendlichen digitalen Ozeanen entwickelt, mit ausgeklügelten Werkzeugen zur Dokumentation von Code und Ideen. Auch, wie wir nach und nach Informationen suchen, hat sich von der Suche nach Lexikoneinträgen entwickelt, um Keywords in Suchmaschinen zu verwenden. Wenn Sie also eine geniale Entdeckung gemacht haben, möchten Sie sicherstellen, dass Sie es gut dokumentieren, damit andere es verstehen und verwenden können. Sie wollen auch sicherstellen, dass andere Ihren Schlag des Genies in digitalen Medien finden. Sie wollen auch sicherstellen, dass andere Ihren Schlag des Genies in digitalen Medien finden. Eine der am weitesten verbreiteten Methoden zur Dokumentierung und Verbreitung von Ideen ist die Verwendung sogenannter Wikis (aus Hawaiian: fast), die leicht in Markdown-Sprache geschrieben werden können. GitHub bietet umfassende, einfach zu lesende Erläuterungen zu Projektdokumentation mit Markdown als Kernelement. Diese Seite stellt die Grundlagen der Markdown-Sprache dar, um Wikis zu nutzen. Darüber hinaus wird die leistungsstarke Alternative zur Verwendung von reStructuredText in Sphinx-basierten Dokumentationen vorgestellt.

Was zu Dokumentieren?¶

Gute Codedokumentation beginnt mit einer qualitativen und präzisen Beschreibung von Software (z.B. einem Python Paket) Kapazitäten, Produkten und Anforderungen. Es bietet auch Workflows für die Installation und Nutzung der Software, bestens mit illustrativen Beispielen. Schließlich ermöglicht ein guter Fehlerbehebungsabschnitt den Benutzern, Probleme in ihrer Daten- oder Softwarenutzung zu finden. Um zukünftige Entwicklung und Wartung zu ermöglichen, bietet ein Contributing Abschnitt * Good-Practice-Richtlinien* zur Kodierung neuer Softwarekapazitäten.

Ihre Software oder Ihr Projekt präsentieren¶

Dieser Abschnitt beabsichtigt, die Vorteile und Kapazitäten der Software zu werben: Benutzer kurz den Zweck der Software, warum es einzigartig ist und was es produziert.

Anforderungen¶

Ein Abschnitt der Anforderungen sollte Benutzern oder Interessenvertretern sagen:

• Welche Systemanforderungen werden benötigt?

• Welche Abhängigkeiten hat die Software oder das Projekt (z.B. andere Python Pakete wie NumP)?

• Welche Eingabedaten werden benötigt, um die Software auszuführen?

Installation¶

Ein Installationsabschnitt sollte die Installation der Software Schritt für Schritt beschreiben (z.B. wie Sie Ihr Python-Paket herunterladen und zugreifen können) oder den Workflow eines Projektes. Screenshots können hilfreich sein. Der Abschnitt Anforderungen sollte bereits geklärt haben, was Benutzer für die Installation benötigen.

Verwendung¶

Ein Abschnitt über die Nutzung sollte beschreiben, wie die Software verwendet werden kann, beginnend mit Grundlagen wie Importieren der Software als Python Paket. Darüber hinaus sollten mögliche Behandlungen von Eingabe- und Ausgabedaten (d.h. Vor- und Nachbearbeitung) erwähnt werden. Wenn verfügbar, fügen Sie in logischer Reihenfolge nacheinander komplexere Funktionalitäten hinzu.

Um Ihre Software wirklich nützlich für andere zu machen, fügen Sie eine Fallstudie hinzu. Die meisten Benutzer werden die detaillierte Codedokumentation nicht lesen, bis sie die Software einmal ausführen und sehen, was sie tun kann. Ein Anwendungsfall hilft auch, die Logik Ihres Codes zu überprüfen und gibt den Benutzern die Möglichkeit, fehlerhafte Codedokumentationsabschnitte an ihren Workflow zu überbrücken. Dies kann manchmal notwendig sein, auch wenn Ihr Code ist sicherlich perfekt und die Dokumentation ist töricht.

Fehlerbehebung¶

Sicher, Ihr Code und Workflow sind fehlerfrei und natürlich macht nur der Benutzer Fehler. Wie auch immer, zeigen Sie Mitgefühl und integrieren spezifische Ausnahme Handling mit try - except-Anweisungen in den Quellcode, die mögliche Fehlerquellen zeigen. Diese Fehlermeldungen (und vielleicht sogar Warnung) sollten alle in einem Troubleshoot Abschnitt der Codedokumentation aufgeführt werden. Jede Fehlerquelle (Message) sollte in Bezug auf folgende Aspekte dokumentiert werden:

• Ursache: Mögliche Gründe, warum ein Fehler auftritt.

• Remedy: Schritte zur Fehlerbehebung.

Beitrag¶

Ihre Software ist brillant. Um die Software noch brillanter, törichter und leistungsfähiger zu machen, ist es eine tolle Idee (wirklich: ein absolutes Muss) um mehr Autoren auf das Entwicklungsteam zu bekommen. Jeder andere Autor hat jedoch wahrscheinlich individuelle Präferenzen, wenn es um Code-Standards geht. Stellen Sie also von Anfang an klare Regeln für andere Beiträge fest. So definieren Sie z.B. klare Code-Konventionen wie im Abschnitt Code Stil und Konventionen erläutert.

Markiert¶

Um eine Dokumentation eines Codes oder Projekts im web-publish-ready Format zu schreiben, ist eine plattformübergreifende Schreibeinstellung erforderlich. Zu diesem Zweck stellt Markdown eine gute Wahl dar (u.a. reStructuredText). Markdown wurde 2004 erstellt und ist eine einfache Markup-Sprache, die intuitiv und einfach zu lernen ist. Markup-Sprachen strukturieren den Inhalt von Klartextdokumenten, wie ein Dokument an Endbenutzer angezeigt wird (Rich Text Format). Andere beliebte Markup-Sprachen sind beispielsweise TeX und XML (Extensible Markup Language). Markdown wurde ein beliebtes Tool zum Schreiben syntaktisch unterscheidbarer Computertexte, der dann in Rich Text Formatgeschmack übersetzt wird. Hier ist ein Beispiel dafür, wie Markdown funktioniert:

# Better than Word-like rich text editors
*OS*-independent functionality:
- Avoid formatting of the same kind of thing redundantly (and inconsistently)
- Backwards compatibility
- Formulae handling
- ... and many more ...

Markdown Editoren (IDEs)¶

Viele Texteditoren bieten Markdown Add-ons und Markdown-nur Editoren verlieren ihre Bedeutung immer mehr. Editoren, die gleichzeitig Markdown und Programmiersprachen wie Python oder R unterstützen, sind Stand der Technik und daher empfohlen.

Basistext-Editoren, die Markdown unterstützen, sind unterhere. Beliebt und multi-platform IDEs for editing Markdown (.md) Dateien sind JupyterLab oder PyCharm.

Markdown Befehlsübersicht und Bilddurchführung¶

The following table and sections provide an overview of basic markdown commands. There are much more options out there, which you can find by using your favorite search engine with the keywords markdown guide.

Feature	Code	Example
Blockquote	`	A quote`
Bold text	**Bold**	Bold
Code block (inline)	inline `code`	inline `code`
Heading 1	# Heading 1	Heading 1
Heading 2	## Heading 2	Heading 2
Heading 3	### Heading 3	Heading 3
Horizontal rule	*** or ===	-------
Hyperlink	[Link](https://fruitsinfo.com)	Link
Hyperlink to section	[Link](https://fruitsinfo.com)#apples	Link to apple-section
Image	
Italic text	*italic*	italic
Numbered list item	1. numbered item	1. Numbered item
Reference (defined)	[Defined Reference][wiki]	Defined Reference
Reference (definition)	[wiki]: https://wikipedia.org	Place at file bottom
Strikethrough	~~Strikethrough~~	~~Strikethrough~~

Posting (Unnummerierte Listen)¶

Posted List Abschnitt kann mit *, + oder --Symbolen mit Registerkarten erstellt werden, die die Listenangabe bestimmen:

* level 1 item
    - level 2 item
    - another level 2 item
        + level 3 item
* next level 1 item

Tabellen¶

Die Tabellenspalten werden durch ein |-Zeichen getrennt. Die erste Zeile bestimmt Zeilenüberschriften und die zweite Zeile die Ausrichtung durch die Verwendung von : (siehe unten Beispiel).

| Fruit | Kingdom | Genus |
|-------|:-------:|------:|
|Banana | Plantae | Musa  |
|Jackfruit|Plantae|Artocarpus|

Converting complex tables from workbooks (e.g., from LibreOffice Calc or MS Excel) is possible with many online tools, and here is just one example from Dave Johnson: https://thisDaveJ.com.

Mathematische Ausdrücke: Gleichungen¶

Mathe-Ausdrücke und Gleichungen können mit $-Zeichen, ähnlich LaTeX implementiert werden.

Html - Markdown¶

• HTML*-Strukturen können in Markdown fehlerfrei verwendet werden, was selbst nichts anderes als vereinfacht html ist. Daher kann jede html-Struktur innerhalb von markdown verwendet werden und die oben gezeigte Gleichungs-Implementierung stellt bereits das erste Beispiel für html-Nutzung in einem Markdown-Dokument dar. Die folgenden Abschnitte geben einen Überblick über einige mehr oder weniger häufig verwendete html-Symbole, die auch mit Markdown arbeiten.

Griechische Briefe¶

Um griechische Buchstaben in Textzeilen zu verwenden, verwenden Sie html Sprache, wobei &lettername; das gewünschte Greek Buchstabensymbol produziert (z.B. Typ δ an Ausgabe δ oder Δ, um einen Kapitalbrief &Delta auszugeben;). Die folgende Tabelle gibt einen Überblick über griechische Buchstabensymbole.

Pfeile und Betreiber¶

Pfeile und Operatoren können auch als html-Symbole implementiert werden. Die folgende Tabelle gibt einen Überblick.

Verschiedene Symbole¶

Markdown profitiert von vielen mehr html-Symbolen, die in Gleichungen oder anderen Texten verwendet werden können. Die folgende Tabelle gibt einen Überblick über derartige verschiedene Symbole.

Wikis¶

Während jedes git-Repository mindestens ein beschreibendes README.md enthalten sollte, bieten wikis viel mehr Detail und Anleitung. Wikis sind eine bequeme Möglichkeit, Benutzer mit dauerhaften Sidebars (wie die Menüleiste auf dieser Website), helfen Benutzern, Methoden und Codes zu verstehen, und kollaborative Codierung mit genauen Beschreibungen von Skripten. GitHub-Benutzer finden Optionen, um wikis im Settings-Tab eines Repository zu aktivieren und die Entwickler verbessern weiterhin wiki-Funktionen (mehr über GitHub’s wikis).

Mehr ausgefeilte wikis sind auf der Jekyll Themen-Website (z.B. der git-wiki Theme) erhältlich. Um Jekyll Themes zu verwenden, stellen Sie sicher, dass Sie GitHub Seiten (im Repository Settings Tab) für das Repository aktivieren, in dem Sie das wiki erstellen möchten (dieses Wiki-Repository ist in der Regel ein anderes Repository zur Beschreibung eines Code-Repository). Dann installieren Sie die Ruby-Entwicklungsumgebung und Jekyll (siehe Anweisungen auf ihrer Website, um Hunderte von Themen für Code- und Projektdokumentation zuzugreifen und zu erstellen. Forked und lokal angepasste Themen können dann mit git an ein entferntes wiki-Repository weitergeleitet werden.

reStructuredText, Sphinx und readthedocs¶

Eine Alternative zu markdown ist reStructuredText, die die Einbettung von Python docstrings (weiterlesen über Code Stil und Konventionen) in jedem Skript mit Sphinx.

Ohne Python oder Programmierkenntnisse, kann es schwierig sein, mit Sphinx zu beginnen. Stellen Sie sicher, Python Grundlagen zu verstehen und dokumentieren Sie jeden Code mit docstrings, bestens mit google styleformatting. Sobald Sie beginnen, Ihr erstes Python Paket zu dokumentieren, wird Google-style docstrings die schnelle Generierung hochwertiger Docs ermöglichen. Derzeit ist eine der besten Optionen für teilweise autogenerierende Codedokumente, für jede Programmiersprache, readthedocs, die auf Sphinx und reStructuredText erstellt.