forked from docs/team-docs
update new documentation page
This commit is contained in:
darknao
parent
b8ecabe4fb
commit
8890b1496f
2 changed files with 66 additions and 43 deletions
|
|
@ -8,7 +8,7 @@
|
|||
|
||||
** Contributing to existing documentation
|
||||
// xref:contributing-docs/contrib-existing-documentation.adoc[Contributing to existing documentation]
|
||||
** xref:contributing-docs/contrib-new-documentation.adoc[Contributing a new documentation site]
|
||||
** xref:contributing-docs/contrib-new-documentation.adoc[Create a new documentation module]
|
||||
** xref:contributing-docs/contrib-quickdocs.adoc[Contributing to Quick Docs]
|
||||
** xref:contributing-docs/contrib-release-notes.adoc[Contributing to Release Notes]
|
||||
|
||||
|
|
@ -33,4 +33,4 @@
|
|||
** xref:contributing-infra/design-ux-contribution.adoc[Design the user interface for Docs]
|
||||
|
||||
//* xref:archive/index.adoc[What we have achieved so far]
|
||||
* What we have achieved so far
|
||||
* What we have achieved so far
|
||||
|
|
|
|||
|
|
@ -1,65 +1,88 @@
|
|||
include::ROOT:partial$attributes.adoc[]
|
||||
|
||||
= Contributing a new documentation sites
|
||||
= Create a new documentation module
|
||||
Francois Andrieu, Fedora Documentation Team
|
||||
2023-04-28
|
||||
|
||||
[abstract]
|
||||
____
|
||||
This section describes how to add a complete new piece of documentation that covers a new area in its entirety. This spans several pages and is usually associated with the creation of a new, dedicated repository. A local working environment is best suited for this. But it is also possible to use the GitLab web IDE.
|
||||
This section describes how to add a completely new piece of documentation that covers a new area in its entirety. This spans several pages and is usually associated with the creation of a new, dedicated repository. A local working environment is best suited for this. But it is also possible to use the web IDE of various GIT forges.
|
||||
____
|
||||
[NOTE]
|
||||
====
|
||||
The following text is slightly outdated, does not take into account the GitLab repositories and still needs to be adjusted.
|
||||
====
|
||||
This section describes how to create and publish new documentation to the docs.fedoraproject.org website.
|
||||
Before you start following this procedure, review all the requirements listed in xref:contributing-docs/index.adoc#prerequisites[Prerequisites].
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
Before creating a new documentation site, consult the {MAILING-LIST}[Discussion forum] first.
|
||||
This is to make sure we can publish your work and you do not waste your time.
|
||||
====
|
||||
Before you start following this procedure, review all the requirements listed in xref:contributing-docs/index.adoc#_prerequisites[Prerequisites].
|
||||
|
||||
. Clone the template repository:
|
||||
link:++https://pagure.io/fedora-docs/template++[]
|
||||
|
||||
. Create a new repository for the new documentation set, or ask someone to create one for you.
|
||||
You can host this repository anywhere but it is recommended to host it on link:++https://pagure.io++[`pagure.io`] where you can reuse Fedora groups to control write access to the repository.
|
||||
Depending on the topic, it may also be best to host it under link:++https://pagure.io/projects/fedora-docs/%2A++[`fedora-docs`].
|
||||
== Documentation repository configuration
|
||||
|
||||
. Clone the newly created repository for your content set.
|
||||
NOTE: While you can create a new repository, or use an existing one, we recommend starting from the provided template repository if you are not familiar with Antora.
|
||||
|
||||
. Copy the contents of the template repository (without the [filename]`.git` directory) into the newly created repository or import the commit history from the template repository.
|
||||
Create your new repository for the new documentation set, or ask someone to create one for you.
|
||||
You can host this repository anywhere but we recommend using https://gitlab.com/fedora[GitLab] where you can use Fedora groups to control write access to the repository.
|
||||
Depending on the topic, it might be preferable to host it under the https://gitlab.com/fedora/docs[Fedora Docs namespace].
|
||||
|
||||
. In the new repository, edit the [filename]`antora.yml` configuration file in the repository root.
|
||||
The file contains comments that point out which parts you need to change.
|
||||
At a minimum, always change the `name` and `title`.
|
||||
On GitLab, you can use `New project` > `Create from template` > `Group` and pick `Documentation Template` in the list.
|
||||
|
||||
. Additionally, edit the [filename]`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 is the `title` and `start_page`.
|
||||
If you are not using GitLab, clone the https://gitlab.com/fedora/docs/templates/fedora-docs-template[template repository] manually and copy the content to your new repository.
|
||||
|
||||
. At this point, when the initial configuration is finished and the repository is configured with the correct name and other required directives, push these changes to the newly created repository (or make a pull request if you can not push directly).
|
||||
This set of changes will be required for any other contributions, so make sure they are in as early as possible.
|
||||
.Example of a simple documentation repository structure
|
||||
----
|
||||
📄 antora.yml
|
||||
📄 site.yml
|
||||
📂 modules
|
||||
📂 ROOT
|
||||
📄 nav.adoc
|
||||
📂 pages
|
||||
📄 index.adoc
|
||||
📄 another-page.adoc
|
||||
----
|
||||
|
||||
. Fork the new repository, so you are not pushing updates directly into it.
|
||||
In the new repository, edit the `antora.yml` configuration file in the repository root.
|
||||
The file contains comments that point out which parts you need to change.
|
||||
At a minimum, always change the `name` and `title`.
|
||||
|
||||
. Start adding the actual ASCIIDoc content.
|
||||
While writing, make sure your new source files are included in the [filename]`nav.adoc` configuration file of the module you are using
|
||||
([filename]`./modules/ROOT/` by default, the location will change based on what you configured in [filename]`antora.yml` earlier).
|
||||
Also make sure to use xref:contributing-docs/tools-localenv-preview.adoc[local preview] often to check your markup.
|
||||
NOTE: The `name` is what will define the final URL of your documentation. In example: `docs.fedoraproject.org/en-US/<name>/`
|
||||
|
||||
. Once you finish, commit your changes and push them to your fork.
|
||||
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`.
|
||||
|
||||
. Use Pagure to make a pull request from your fork to the main repository's `master` branch.
|
||||
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.
|
||||
|
||||
. Someone will see your pull request and either merge it, or provide feedback if there is something you should change.
|
||||
Work with the people commenting to make sure your contributions are up to standards.
|
||||
== Writing documentation
|
||||
|
||||
Some useful documentation links:
|
||||
|
||||
- xref:contributing-docs/asciidoc-markup.adoc[]
|
||||
- xref:contributing-docs/style-guide.adoc[]
|
||||
|
||||
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 xref:contributing-docs/tools-localenv-preview.adoc[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 https://gitlab.com/fedora/docs/docs-website/docs-fp-o/-/blob/prod/site.yml[main Antora playbook].
|
||||
|
||||
To add a new documentation module, you will need to add its repository to the `content.sources` list:
|
||||
|
||||
[,yaml]
|
||||
----
|
||||
content:
|
||||
sources:
|
||||
- url: https://gitlab.com/path/to/new/repository.git
|
||||
branches: main <.>
|
||||
start_path: docs <.>
|
||||
----
|
||||
<.> 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 https://gitlab.com/fedora/docs/docs-website/docs-fp-o/-/issues[Fedora Docs Website repository], and the Documentation Team will handle that part for you.
|
||||
|
||||
. Your new content will need to be published for the first time, and at the moment this does not happen automatically.
|
||||
Send an e-mail to the {MAILING-LIST}[docs mailing list] asking for your content to be published.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
If nobody reacts to your Pull Request after 5 days, xref:ROOT:index.adoc#find-docs[get in touch with the Docs Team].
|
||||
We might have missed the email for your Pull Request.
|
||||
If you do not get any update to your Merge Request or ticket after 5 days, xref:ROOT:index.adoc#find-docs[get in touch with the Docs Team].
|
||||
====
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue