Użyj Sphinx do utworzenia dokumentacji w wielu formatach w CentOS 7

• Wymagania wstępne
• Krok 1: Zaktualizuj system
• Krok 2: Zainstaluj pip i Sphinx
• Krok 3: Skonfiguruj podstawową konfigurację dokumentacji
• Krok 4: Zbuduj hierarchię dla swojej dokumentacji
• Krok 5: Utwórz pliki źródłowe określone powyżej
• Krok 6: Wydrukuj wersję HTML swojej dokumentacji

Sphinx to przydatne narzędzie oparte na języku Python dla techników i pisarzy, które pozwala im z łatwością tworzyć elegancką, w pełni funkcjonalną dokumentację w różnych formatach. Dzięki Sphinx piszesz dokumenty za pomocą reStructuredText - lekkiego języka znaczników - na początek, a następnie możesz uzyskać wynik w wielu formatach, w tym HTML, LaTeX, PDF, ePub i innych.

W tym samouczku omówimy proces instalacji i używania Sphinxw instancji CentOS 7 x64 na platformie Vult.

Wymagania wstępne

• Instancja CentOS 7 x64.
• Użytkownik sudo .

Krok 1: Zaktualizuj system

sudo yum update
sudo shutdown -r now

Krok 2: Zainstaluj pip i Sphinx

sudo yum install -y python-devel python-setuptools python-pip
sudo pip install --upgrade pip
sudo pip install -U Sphinx

Krok 3: Skonfiguruj podstawową konfigurację dokumentacji

Przed rozpoczęciem użytkowania Sphinxmusisz określić katalog źródłowy, w którym Sphinxzostanie uruchomiony i zapisać całą dokumentację. Po utworzeniu katalogu, którego chcesz używać, możesz uruchomić, sphinx-quickstartktóry zainicjuje Sphinxi utworzy wymaganą konfigurację podstawową.

sphinx-quickstart jest podobny do kreatora konfiguracji, który zadaje pytania, które określają aspekty twojego projektu.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Krok 4: Zbuduj hierarchię dla swojej dokumentacji

Domyślnie sphinx-quickstartkreator utworzy kilka katalogów i plików.

_build           # The directory for containing Sphinx output
conf.py          # The file containing your project configurations
index.rst        # The master file containing the hierarchy of your documentation
make.bat         # A Windows command file
Makefile         # A file necessary for running the make command
_static          # The directory for static files, including custom stylesheets, pictures, etc.
_templates       # The directory for custom templates

Rzućmy okiem na plik główny index.rst, który zawiera hierarchię twojej dokumentacji; mianowicie drzewo spisu treści lub toctree.

Otwórz go za pomocą edytora tekstu:

vi index.rst

Podczas przeglądania pliku zauważysz sekcję o nazwie toctree. Jeśli masz inne pliki źródłowe ( *.rst) do swojej dokumentacji, musisz je określić w toctreesekcji: .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Konieczne jest:

• Pozostaw pusty wiersz nad wprowadzonymi danymi.
• Nie sufikuj plików źródłowych za pomocą .rst.
• Umieść pliki źródłowe w odpowiedniej kolejności.
• Użyj tylko jednej nazwy pliku na wiersz.
• Wcięcie nazw plików za pomocą :maxdepth: 2.

Po zakończeniu modyfikacji zapisz plik i zamknij edytor tekstu.

ESC
:!wq

Krok 5: Utwórz pliki źródłowe określone powyżej

Pliki źródłowe muszą zostać utworzone z nazwami zgodnymi z wcześniej określonymi, w index.rstprzeciwnym razie nie zostaną uwzględnione w końcowym wyniku.

Wszystkie pliki źródłowe muszą być zgodne z reStructuredText markup language. Aby uzyskać więcej informacji, odwołaj się do reStructuredText Primer .

Krok 6: Wydrukuj wersję HTML swojej dokumentacji

Po zakończeniu tworzenia dokumentacji możesz wydrukować swoją pracę HTML format , wykonując poniższe polecenie:

make html

Dane wyjściowe zostaną zapisane w katalogu, ./\_build/htmlktóry zawiera wszystko, co niezbędne do przeglądania pliku podczas przeglądania stron internetowych.

To kończy nasz samouczek.