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>/% |
Additionally, edit the site.yml configuration file. Note that this file is only used when building a local preview of your content set - on the website it is overridden by the site-wide site.yml configuration. The only directives you need to edit in this file are the title and start_page.
At this point, the initial configuration is complete. You can push these changes to the newly created repository (or make a pull request if you do not have the required rights) and start working on writing the actual documentation.
Writing documentation
Some useful documentation links:
If your documentation is made of several pages, you can list them in the nav.adoc. This file will then be used to build the navigation menu on the left side of docs.fp-o.
While you’re writing, you can use the local preview to check the resulting document.
Publish a new documentation module
Once the repository is set up, and initial content added, it is ready to be published.
Documentation modules published on docs.fp-o are all listed in the main Antora playbook.
To add a new documentation module, you will need to add its repository to the content.sources list:
content:
sources:
- url: https://gitlab.com/path/to/new/repository.git
branches: main (1)
start_path: docs (2)
| 1 | The default branch is set to master. If your repository is using any other name (main for instance), you need to specify it here. <.> This setting is optional. If the documentation files are stored in a subdirectory on your repository (/docs/ for instance), you must set its relative path here, without leading or trailing slashes. If it is located at the root level, as documented on this page, you can omit this parameter. |
You can either create a Merge Request with these changes, or if you do not feel comfortable editing this file, create a ticket on the Fedora Docs Website repository, and the Documentation Team will handle that part for you.
|
If you do not get any update to your Merge Request or ticket after 5 days, get in touch with the Docs Team. |
Want to help? Learn how to contribute to Fedora Docs ›