I forrige uke, i Write Dokumentasjon gang Output flere formater med Sphinx vi lærte å installere Sphinx dokumentasjon generator, og hvordan bygge HTML, PDF, Epub, og andre dokumenter fra en ny Sphinx installasjon. I dag skal vi lage en liten testprosjekt med noe originalt innhold og merke det opp med RST, mors Sphinx kodespråk. Deretter kan du bygge flere formater fra én kilde. Alt du trenger er din favoritt teksteditor og en fungerende Sphinx installasjon.
Eksempelet prosjekt for denne artikkelen er enkel og demonstrerer det essensielle. Start med å laste ned den viktigste eksemplet siden, example.rst
, den skjermbilde av gjengitt HTML-side, sfinksen-html-page.png
, og de andre prosjektfiler fra Google-stasjonen. example.rst
er en Sphinx kildefilen, og sfinksen-html-page.png
viser hvordan det ser ut etter å ha kjørt gjøre html
kommando.
Sanity Tips
Når du trenger hjelp alltid forholde seg til Sphinx referansehåndboken, i stedet for å kaste bort tid på nettet søker full av gale svar.
Sphinx er skrevet i Python, så blanke saker . Kjør hyppig bygger, da dette er den raskeste måten å finne kodefeil. Dette eksemplet fra å kjøre gjøre html I eksempelet prosjekt for denne artikkelen, prosjektet filstrukturen ser slik ut: book1 Dine kildefiler bør ha .rst Titler og underoverskrifter er merket opp med en rekke skilletegn. Du kan bruke hva skilletegn du liker, eller pryd Din innholdsfortegnelsen side er definert i conf.py MAXDEPTH Husk at alle filbaner (i innholdsfortegnelsen, kryssreferanser og bilde lenker) står i forhold til ditt prosjekt roten. I del 1 vi lærte å liste opp og kjøre våre tilgjengelige bygge kommandoer. Når du å kjøre en bygge kommando, for eksempel gjøre html Nå bør ha de opprinnelige kildefilene i fire forskjellige pent formatert utganger. Hva gjør du nå? Sjekk ut Sphinx dokumentasjon for flere funksjoner og avansert funksjonalitet, og starter med hvordan du bruker conf.py for avansert prosjektstyring. Public domain bilder av Månen og Jorden høflighet Earth Science and Remote Sensing Unit, NASA Johnson Space Center
finner en feil, og forteller oss nøyaktig hvor det er:
book1 $ lage html [...] /home /Carla /book1 /content /example.rst : 23: ADVARSEL: Tittel understreker også short.First-nivå underoverskrift =================
Dokumentasjon Struktur
book1 | --_ build | - conf.py | - innhold | - eksempel-2.rst | - example.rst | - bilder | - blue-marble.jpg | - måne-fra-space.jpg | - index.rst | - Makefile | - _static | - _templates
er prosjektets rotkatalogen. Når du kjører din bygge kommandoer, går produksjonen inn i _build katalog. Alle filene ble opprettet av sfinksen-quickstart
script (se del 1), bortsett fra innhold Hotell og bilder
kataloger. De er mine eksempel innholdsfiler, og index.rst
ble endret til å omfatte innholdsfilene.
filtypen. (Dette er konfigurerbart i conf.py
med source_suffix
parameter.) Når du refererer til ditt .rst
filer i interne lenker og innholdsfortegnelsen bare bruker den filnavn og utelate forlengelse. For bildefiler må du oppgi hele filnavn, inkludert filtypen.
som Sphinx manuell kaller dem; rekkefølgen på siden din avgjør hvordan de gjengi. Dine pryd må være samme lengde som overskrifter. Hvis de ikke vil du se advarsler i din build utgang.
med master_doc
parameter. For dette prosjektet TOC kildefilen er index.rst
. Eksempelet prosjektet er enkel, med bare to sider, slik at innholdsfortegnelsen er enkel:
.. index.rst ================= Innhold == =============== .. toctree ::: MAXDEPTH: to content /eksempel content /eksempel-2
styrer hvor mange nivåer av underoverskrifter innholdsfortegnelsen skjermer, så : MAXDEPTH: 2
viser sidetittelen og andre nivå overskrifter. Du trenger ikke å kalle det "Innhold", men kan kalle det hva du vil. Prefacing en linje med to prikker og en plass hindrer den fra å vises i det endelige resultatet, slik at du kan bruke dette for kommentarer samt formatering direktiver. I innholdsfortegnelsen eksempel .. index.rst
er en kommentar og .. toctree ::
er en formatering direktiv.
Bygg din Project
, husk å alltid kjøre gjøre rent Anmeldelser først. Når du kjører flere forskjellige bygger på rad, ikke løpe gjøre rent
fordi dette sletter innholdet i build-katalogen. I stedet kjøre dem i rekkefølge, slik at de vil alle vises i _build katalog:
$ gjøre latexpdf $ gjøre mennesker $ make epub $ make tekst $ ls _builddoctrees latexmanepub tekst