Luo uusi dokumentaatiomoduuli
Tässä osiossa kuvataan, miten voit lisätä kokonaan uuden dokumentaation, joka kattaa uuden alueen kokonaisuudessaan. Tämä ulottuu useille sivuille, ja se liittyy yleensä uuden, erillisen arkiston luomiseen. Paikallinen työympäristö sopii tähän parhaiten. Mutta on myös mahdollista käyttää erilaisten GIT-takomoiden verkko-IDE:tä.
Ennen kuin alat noudattaa tätä menettelyä, käy läpi kaikki vaatimukset, jotka on listattu kohdassa Edellytykset.
Dokumentaatiovaraston määritys
| Vaikka voit luoda uuden repositorion tai käyttää olemassa olevaa, suosittelemme aloittamaan annetusta mallipohjavarastosta, jos et tunne Antoraa. |
Luo uusi arkisto uudelle dokumentaatiojoukolle tai pyydä jotakuta luomaan sellainen puolestasi. Voit isännöidä tätä arkistoa missä tahansa, mutta suosittelemme käyttämään GitLab:ta, jossa voit käyttää Fedora-ryhmiä hallitsemaan arkiston kirjoitusoikeuksia. Aiheesta riippuen saattaa olla parempi isännöidä sitä Fedora Docs -nimiavaruus.
GitLabissa voit käyttää %New project% > %Create from template% > %Group% ja valita %Documentation Template% listasta.
Jos et käytä GitLabia, kloonaa template repository manuaalisesti ja kopioi sisältö uuteen repositorioosi.
📄 antora.yml
📄 site.yml
📂 modules
📂 ROOT
📄 nav.adoc
📂 pages
📄 index.adoc
📄 another-page.adoc
Uudessa repositoriossa muokkaa %antora.yml % konfiguraatiotiedostoa repositorion juuressa. Tiedostossa on kommentteja, jotka osoittavat, mitä osia sinun täytyy muuttaa. Vähintäänkin vaihda aina %name% ja %title%.
| %name% määrittää dokumentaatiosi lopullisen URL-osoitteen. Esimerkiksi: %docs.fedoraproject.org/en-US/<name>/% |
Muokkaa lisäksi site.yml-määritystiedostoa. Huomaa, että tätä tiedostoa käytetään vain, kun sisältösi paikallinen esikatselu luodaan – verkkosivustolla se korvataan koko sivuston laajuisella site.yml-määrityksellä. Ainoat tässä tiedostossa muokattavat direktiivit ovat title ja start_page.
Tässä vaiheessa alkuasetukset ovat valmiit. Voit julkaista muutokset juuri luotuun repositorioon (tai tehdä pull-pyynnön, jos sinulla ei ole tarvittavia oikeuksia) ja aloittaa varsinaisen dokumentaation kirjoittamisen.
Dokumentaation kirjoittaminen
Joitakin hyödyllisiä dokumentaatiolinkkejä:
Jos dokumentaatiosi koostuu useista sivuista, voit listata ne tiedostossa nav.adoc. Tätä tiedostoa käytetään sitten docs.fp-o-tiedoston vasemmalla puolella olevan navigointivalikon rakentamiseen.
Kirjoittamisen aikana voit tarkistaa tuloksena olevan dokumentin paikallinen esikatselu -tiedoston avulla.
Julkaise uusi dokumentaatiomoduuli
Kun arkisto on määritetty ja alkuperäinen sisältö lisätty, se on valmis julkaistavaksi.
Kaikki docs.fp-o-sivustolla julkaistut dokumentaatiomoduulit on lueteltu tiedostossa Antoran pääkäsikirja.
Uuden dokumentaatiomoduulin lisäämiseksi sinun täytyy lisätä sen arkisto 'content.sources'-listalle:
content:
sources:
- url: https://gitlab.com/path/to/new/repository.git
branches: main (1)
start_path: docs (2)
| 1 | Oletushaara on asetettu 'masteriksi'. Jos arkistosi käyttää jotain muuta nimeä (esimerkiksi 'main'), sinun täytyy määritellä se tässä. <.> Tämä asetus on vapaaehtoinen. Jos dokumentaatiotiedostot ovat tallennettuna alihakemistossa repositoriossasi (esimerkiksi '/docs/'), sinun täytyy asettaa sen suhteellinen polku tänne ilman etu- tai loppuviokuvia. Jos se sijaitsee juuritasolla, kuten tällä sivulla on dokumentoitu, voit jättää tämän parametrin pois. |
Voit joko luoda yhdistämispyynnön näillä muutoksilla, tai jos et tunne oloasi mukavaksi muokata tätä tiedostoa, luo tiketti Fedora Docs Website repository -sivustolle, ja dokumentaatiotiimi hoitaa tämän puolestasi.
|
Jos et saa päivitystä Merge Requestiin tai tikettiin viiden päivän kuluessa, ota yhteyttä Docs-tiimiin. |
Want to help? Learn how to contribute to Fedora Docs ›