The Sphinx Python Documentation Generator ble opprinnelig opprettet for å bygge Python dokumentasjon, og da er det utviklet seg til en god generell dokumentasjon skaperen. Det er spesielt godt egnet til å skape teknisk dokumentasjon, med støtte for bilder, kryssreferanser, automatiske indekser, fleksible innholdsfortegnelser, henvisninger og fotnoter. Fra en enkelt kilde fil kan du opprette en- eller flersiders HTML, PDF, ePub, JSON, latex, Texinfo, man-sidene, og ren tekst dokumenter.
Sphinx mors markup language er reStructuredText (RST), og parsing og sette håndteres av Docutils. RST er lett å lære og fullt dokumentert. Når du bygger og forhånds utskriftene dine sider, finner Sphinx automatisk kodefeil for deg.
Installere Sphinx
På de fleste Linux-distribusjoner Sfinxen pakken er python-sfinks
. Dette bør installere en rekke avhengigheter som Python, Docutils, Pygments, LaTeX, og ulike utvidelser.
Sphinx har mange utvidelser, og et godt alternativ for å håndtere dem som ikke er avhengig av distro emballasje bruker pip Sphinx inneholder et skript, sfinksen-quickstart Dette stiller deg en rekke. spørsmål. Svarer ja på alt; det gjør ikke vondt noe og sikrer at du har full funksjonalitet, og du kan alltid gjøre endringer senere. Når du er ferdig med det ser slik ut: Dine katalogen innholdet skal se slik ut: Gå videre og kjøre noen build-kommandoer for å se hva som skjer, som gjøre html Dette skaper en bygge bedriftskatalog; skriv dette for å finne og se på den nye HTML-side. Figur 1 (over) viser resultatet Run gjøre hjelp Sphinx inkluderer ikke seere for utdatafiler, så du må finne din egen. For eksempel åpne HTML-filer med en nettleser, ePub filer med en Epub-leser, og leser man-sidene med mannen kommandoen: Og se, din ny mann side (figur 2). Selvfølgelig eksempelet er tom, fordi vi ikke har opprettet noe innhold enda. Run gjøre rent Sphinx er avhengig av LaTeX, og du vil sannsynligvis se feilmeldinger om manglende utvidelser når du bygger dokumenter; for eksempel mangler pdflatex Det er også vanlig på en ny Sphinx installasjon for å se feilmeldinger om manglende .sty The basen texlive Du kan unngå distro emballasje drama ved hjelp av TeX Live for å installere og administrere TeX pakker direkte fra kilden. Bruk litt tid på å bli kjent med conf.py Sphinx kommer med et sett med innebygde temaer.: Du kan se hva noen av disse ser ut ved å skrive inn temanavn i "Alternativer for HTML-utgang" i conf.py De innebygde temaer har alternativer som du kan konfigurere i conf.py Now at du vet hvordan du installerer Sphinx og lage din egen bygger, kommer tilbake neste uke for å lære å lage og formatere innholdet. Anmeldelser
(PIP installerer pakker), Python pakkesystem, for å installere pakker direkte fra PyPI, Python Package Index. Python Package Index er den offisielle Python-pakken depotet. På de fleste Linux distroer pip
kommer i python-pip pakke
. Installer Sphinx denne måten med pip Bilde:
$ sudo PIP installere sfinksen
Første oppsett
, å lansere det nye prosjektet og skape sin opprinnelige konfigurasjonen. Den ber deg en rekke spørsmål som prosjektnavn, forfatter og katalogstruktur, og lagrer dine svar i conf.py
fil. Opprett og angi en ny katalog for prosjektet, og deretter kjøre skriptet:
$ mkdir book1 $ cd book1 $ sfinksen-quickstartWelcome til Sphinx 1.3.1 quickstart verktøyet
Lage fil ./source/conf.py.Creating fil ./source/index.rst.Creating fil ./Makefile.Creating fil ./make.bat. Ferdig:. En innledende katalogstrukturen har blitt opprettet
book1 $ lsbuild make.bat Makefile kilde
å opprette websider:
book1 $ lage html
å se alle dine bygge mål, eller se i prosjektets Makefile.
book1 $ gjøre helpPlease bruk `lage" der er en av html å lage frittstående HTML-filer dirhtml å lage HTML-filer som heter index.html i kataloger singlehtml å gjøre en eneste stor HTML-fil pickle å lage sylte filer json å lage JSON-filer Htmlhelp å lage HTML-filer og HTML hjelp prosjektet qthelp å lage HTML-filer og en qthelp prosjekt applehelp å gjøre en Apple Help Book devhelp å lage HTML-filer og en Devhelp prosjekt epub å gjøre en epub latex for å gjøre LaTeX-filer, kan du sette PAPIR = a4 eller PAPIR = brev [. ..]
book1 $ mann build /mann /thefoomanual.1
før du kjører en annen build å sikre at du starter med en tom bygge katalogen.
når du prøver å bygge en PDF-fil:
book1 $ gjøre latexpdfsphinx-bygge-b latex -D bygge /doctrees kilde build /latexRunning Sphinx v1.3.1making utgang katalogen ... [...] gjør [1]: pdflatex: Command ikke foundmake [1]: *** [TheFooManual.pdf] Feil 127make [1]: Leaving katalogen `/home /Carla /book1 /build /latex 'gjøre: *** [latexpdf] Feil 2
filer. Den sikre måten å kurere disse feilene er å installere alle texlive
pakker, som du kan få på Debian med metapakke texlive-full
. Dette inkluderer utvidelser språk, vitenskap og matematikk, så det er ca 1,5 gigabyte, og installerer til 3GB. Installere følgende (Debian /Ubuntu /Mint) skal gi deg alt du trenger uten å måtte installere hele works:
texlive
texlive-base
texlive-extra-utils
texlive-font-utils
texlive-fonts-recommended
texlive-latex-extra
texlive-latex-recommended
pakken på CentOS er ganske omfattende, og CentOS gir et stort antall mindre Texlive pakker slik at du kan installere hva du vil uten å måtte installere en gigantisk blob av alt. Fedora har en tre bjørnene meta-emballasje ordning: texlive-ordningen-full
, texlive-ordningen-medium
, og texlive-ordningen-basic
, og som CentOS, et stort antall små pakker.
Kontrollere Prosjekt alternativer
< p> conf.py
filen i prosjektet rotkatalogen styrer alle prosjektets alternativer, og dette er filen du vil redigere for å endre noen alternativer du valgte da du kjørte sfinksen-quickstart
. For eksempel, hvis du svarte ja på "inkludere lenker til kildekoden til dokumenterte Python objekter", så hver gang du kjører en build du må vente på "loading intersphinx inventar fra https://docs.python.org/objects. inv ... ". Deaktivere denne ved å skrive inn ditt conf.py Hotell og kommentere ut sphinx.ext.intersphinx
forlengelse i "General konfigurasjon" -delen.
; det er lett å endre verdiene og deretter bygge prosjektet for å se hva endringene ser ut. Det er der du konfigurere prosjektnavn, versjon, opphavsrett, utvidelser og utenheter for ulike formater
Web Page Temaer
basic
alabaster
sphinx_rtd_theme
classic
sphinxdoc
scrolls
agogo
nature
pyramid
haiku
traditional
epub
bizstyle
, og deretter kjører gjøre html Bilde:
< pre> html_theme = 'pyramiden'
, og disse er dokumentert i Sphinx supportside HTML theming. For egendefinerte temaer ikke gjør dette, for det er banen til galskap, da dette vil gjøre ditt conf.py
rotete og uhåndterlig. Det er bedre å sette den tilpassede tema i sin egen katalog, og deretter inn den relative katalogbanen (i forhold til prosjektets rotkatalogen) i conf.py Bilde:
html_theme_path = ['. ./custom_theme']