De ce sunt aici?

Tu, cititorul, ești aici pentru că ai scris un instrument minunat în Python și vrei să îl faci accesibil și ușor de utilizat.

Eu, scriitorul, sunt aici pentru că am fost chiar acolo unde ești acum câteva luni. Am vrut să folosesc Sfinx pachet pentru a crea o documentație în stil ReadTheDocs pentru proiectul meu.

Am găsit onboarding-ul Sphinx netrivial, motiv pentru care am făcut-o această repo GitHub care poate fi folosit ca șablon pentru ta proiect.

Înainte de a începe, câteva ipoteze de bază, pentru a ne asigura că suntem pe aceeași pagină:

  • Scrii în Python.
  • Ai scris docstrings pentru bucățile de cod pe care doriți să le documentați.
  • Scopul tău este să faci un ReadTheDocs-documentare de stil care, cel puțin parțial, se va genera automat.
  • Sunteți conștient de faptul că în 10 minute puteți publica prima versiune din documentația dvs., va arăta ceva de genul acest:
Ghicitoarea Sfinxului Cum sa va documentati codul cu usurinta

Partea 1 – Setarea scenei

  • Instalați Sphinx: pip install sphinx
  • Mergi la github.com/DalyaG/Sphinx185:
  • Descărcați folderul documentation_template_for_your_next_project
  • Copiați în proiectul dvs.
  • Redenumiți folderul documentation
1611450905 870 Ghicitoarea Sfinxului Cum sa va documentati codul cu usurinta

Partea 2 – Personalizați

  • Deschideți fișierul <your_project>/documentation/conf.py în editorul dvs. preferat. Căutați pattern #CHNAGEME # și urmați instrucțiunile.
  • În mod similar, editați fișierul <your_project>/documentation/index.rst și urmați instrucțiunile în linie.
1611450906 844 Ghicitoarea Sfinxului Cum sa va documentati codul cu usurinta
1611450906 964 Ghicitoarea Sfinxului Cum sa va documentati codul cu usurinta
1611450907 459 Ghicitoarea Sfinxului Cum sa va documentati codul cu usurinta

Partea 3 – Adăugați conținutul pe care doriți să îl documentați

  • Să presupunem că aveți un fișier python numit my_amazing_class.py care include o clasă pe care doriți să o documentați.
  • În același folder dupa cum conf.py și index.rst fișiere, creați un fișier nou numit my_amazing_class.rst și copiați-lipiți-personalizați acest șablon:
This is a template for including classes========================================|.. autoclass:: my_amazing_class.MyAmazingClass|:ref:`Return Home <mastertoc>`

SFAT: asigurați-vă că folderul care conține clasa dvs. uimitoare se află în PYTHONPATH și că include un fișier init__init__.py

  • În index.rst fișier, editați Cuprinsul pentru a include numele fișierului .rst fişier:
.. toctree::   :maxdepth: 1   :name: mastertoc
   my_amazing_class

Partea 4 – „Compilați”

  • În terminal, în interiorul documentation folder, rulați make clean html.
  • Asta e! Aveți prima versiune a documentației gata de vizualizare!
  • Deschideți fișierul documentation/_build/html/index.html în browserul tău și vezi singur 🙂
1611450907 864 Ghicitoarea Sfinxului Cum sa va documentati codul cu usurinta
1611450908 723 Ghicitoarea Sfinxului Cum sa va documentati codul cu usurinta

Partea 5 – Gazdă pe paginile GitHub

  • Sub rădăcina proiectului dvs., deschideți un nou folder numit docs și copiați în interiorul său conținutul <your_project>/documentation/_build/ html /
  • În interiorul acestui nou docs folder, creați un fișier gol numit .nojekyll
    (Aceasta îi spune GitHub Pages să ocolească valoarea implicită Jekyll teme și utilizați HTML și CSS în proiectul tău)
  • Împingeți modificările la master ramură.
  • În depozitul dvs. de pe GitHub, accesați Settings->GitHub Pages->Sursă
    și select master branch/docs pliant
1611450908 778 Ghicitoarea Sfinxului Cum sa va documentati codul cu usurinta
1611450909 168 Ghicitoarea Sfinxului Cum sa va documentati codul cu usurinta

Partea 6 – Împărtășește!

Da. Asta e. Așteptați câteva minute pentru ca GitHub să se actualizeze. Împărtășiți-vă frumosul site de documentare la

https://<your_git_usrname>.github.io/<project_name> /

SFAT: Când actualizați documentația, trebuie să ștergeți fișierul docs folder și creați-l din nou. Vezi mai multe detalii aici.

Epilog

Aceasta este partea în care spun ceva gânditor despre cât de minunat este să creezi conținut nou în lume. Și ce persoană minunată ești pentru că ai ales să-ți faci conținutul original disponibil, accesibil și ușor de utilizat.

Dar hei, ai reușit până aici, așa că știi deja aceste lucruri.

Așadar, dacă mai este ceva ce simți că nu știi, te invit să explorezi site-ul de documentare Am făcut pentru acest tutorial. Puteți urmări vorbă am dat despre Sfinx. Sperăm că acestea vor răspunde la câteva enigme care ți-au rămas despre Sfinx.