Paikallisen esikatselun luominen

Fedora Documentation Team Last review: 2023-03-19
Paikallinen esikatselu on arvokas työkalu muutosten testaamiseen, kun työskentelet paikallisessa kirjoitusympäristössä. Aja docsbuilder-skripti, joka on saatavilla Fedora-sisältövarastossa. Voit rakentaa ja ajaa täysin renderöidyn sivuston koneellasi esitarkastellaksesi muutoksiasi ennen kuin teet pull-pyynnön Fedora-sisältövarastoihin.

Kun tarvitset paikallisen esikatselun

Kun työskentelet paikallisen luontiympäristön kanssa, paikallinen esikatselu tarjoaa monipuolisen työnkulun testata, miten muutokset renderöidään ja miten ne toimivat selaimessasi paikallisesti. Kun teet muutoksia, kuten, mutta ei rajoittuen;

  • Vaihda linkkejä tai korjaa rikkinäiset linkit

  • Muuta dokumentti ristiviittauksiksi xref-viittausten avulla

  • Yhdistä useita sivuja yhdeksi sivuksi

  • Päivitä kuvia tai korjaa rikkinäiset kuvat

  • Lisää metatietoja tai vaihtoehtoista tekstiä kuviin

  • Osiotasot järjestetty uudelleen (esim. h2–h3, h3–h4) luettavuuden ja lukukulun vuoksi

  • Korjaa passiivinen navigointipalkki

  • Navigointipalkin uudelleenjärjestely

  • Kirjoita vanhentuneet sivut uudelleen

  • Lisää AsciiDoc-attribuutit

  • Reiterate changes and tests with vale linter

Sinun on luotava skriptejä muutosten ennakoitavaksi renderöimiseksi ja testattava niitä ennen pull-pyynnön tekemistä.

Mitä skriptit tekevät

Yhtenäinen dokumenttien rakennusskripti, docsbuilder.sh, rakentaa sivustosta paikallisen version, joka tarkoittaa koko sivuston osajoukkoa, joka sijaitsee paikallisessa arkistossasi. Skripti puolestaan käynnistää web-palvelimen ja palvelee sivustoa osoitteessa http://localhost:8080/. Tämän linkin avaaminen millä tahansa web-selaimella näyttää esikatselun, joka on käytettävissä, kunnes lopetat prosessin (kbd:[Ctrl+C] terminaalissa).

Tarkista projektien aloitussivulta README.md-tiedosto suorittaaksesi ehdotetun skriptin.

Muutosten testaaminen

Siirry hakemistoon, jossa kloonattu repo sijaitsee, rakenna, katso ja esikatsele sivustoa suorittamalla rakennusskriptit terminaalissa.

$ ./docsbuilder.sh

Pagure tai muut sisältövarastot näyttävät eri builder-skriptin.

$ ./builder.sh

Skriptien käyttämiseen tarvitset [application]'Podman' asennettuna, jos käytät Fedora Linuxia, tai [application]'Docker CE', jos käytät macOS:ää.

Useiden repositorioiden esikatselu

Jos työsi kattaa sisältöä useissa repositorioissa, esimerkiksi koska link to another repository, voit laajentaa esikatselua lisäämällä 'site.yml'-repositorioita seuraavasti:

content:
  sources:
  - url: .
    branches: HEAD
  - url: https://pagure.io/fedora-docs/another-repository.git
    branches: main

Correct entries to use can be found from docs-fp-o site.yml.

Tavallisten Antoran kirjoitusjärjestelmien käyttö

Jos haluat käyttää tavallista Antoran rakennus- ja esikatselutyönkulkua – seuraa ohjeita Antora Documentation page -sivulla.

Once you have Antora CLI and Antora Site Generator you can build and preview the pages without the container scripts.

Projektihakemiston sivujen rakentamiseksi suorita:

antora generate site.yml

This will create a new directory public which contains all the necessary files. Navigate there and run a server command. You might already have a Python simple server, in which case run:

python3 -m http.server

or if you only have Python 2 on your machine:

python -m SimpleHTTPServer

It opens a local preview at port 8000.

If you have cargo (Rust package manager), you could also install and use miniserve or any other simple server of your choice for that matter.

Want to help? Learn how to contribute to Fedora Docs ›