| |
@@ -1,39 +1,56 @@
|
| |
- = Adding new documentation to the site
|
| |
+ include::ROOT:partial$attributes.adoc[]
|
| |
|
| |
- This section describes how to add new documentation to the website and ensure it is published and listed somewhere. Before you start following this procedure, make sure that you fulfill all the requirements listed in xref:prerequisites.adoc[Prerequisites].
|
| |
+ = Create and publish new documentation sites
|
| |
+
|
| |
+ 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:prerequisites.adoc[Prerequisites].
|
| |
|
| |
[IMPORTANT]
|
| |
====
|
| |
- Before you start creating an entirely new documentation set, consult the mailing list to make sure your work is accepted by the project and you do not spend time developing docs that will be rejected in the end.
|
| |
+ Before creating a new documentation site, consult the {MAILING-LIST}[mailing list] first.
|
| |
+ This is to make sure we can publish your work and you do not waste your time.
|
| |
====
|
| |
|
| |
- . Clone the template repository: link:++https://pagure.io/fedora-docs/template++[]
|
| |
+ . Clone the template repository:
|
| |
+ link:++https://pagure.io/fedora-docs/template++[]
|
| |
|
| |
- . Create a new pagure repository for the new documentation set, or ask someone to create one for you. The new repository should be listed under link:++https://pagure.io/projects/fedora-docs/%2A++[`fedora-docs`].
|
| |
+ . Create a new pagure repository for the new documentation set, or ask someone to create one for you.
|
| |
+ The new repository should be listed under link:++https://pagure.io/projects/fedora-docs/%2A++[`fedora-docs`].
|
| |
|
| |
. Clone the newly created repository for your content set.
|
| |
|
| |
. Copy the contents of the template repository (without the [filename]`.git` directory) into the newly created repository.
|
| |
|
| |
- . 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`.
|
| |
+ . 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`.
|
| |
|
| |
- . 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`.
|
| |
+ . 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`.
|
| |
|
| |
- . 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.
|
| |
+ . 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.
|
| |
|
| |
. Fork the new repository, so you are not pushing updates directly into it.
|
| |
|
| |
- . 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:local-preview.adoc[local preview] often to check your markup.
|
| |
+ . 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:local-preview.adoc[local preview] often to check your markup.
|
| |
|
| |
. Once you finish, commit your changes and push them to your fork.
|
| |
|
| |
- . Use pagure to make a pull request from your fork to the main repository's master branch.
|
| |
+ . Use Pagure to make a pull request from your fork to the main repository's `master` branch.
|
| |
+
|
| |
+ . 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.
|
| |
+
|
| |
+ . 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.
|
| |
|
| |
- . 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.
|
| |
- +
|
| |
[NOTE]
|
| |
====
|
| |
- If nobody reacts to your pull request in several days, try bringing it up on one of the link:++https://apps.fedoraproject.org/calendar/docs/++[weekly meetings], the IRC channel (`#fedora-docs` on FreeNode), or the link:++https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org/++[mailing list].
|
| |
+ 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.
|
| |
====
|
| |
-
|
| |
- . 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 link:++https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org/++[docs mailing list] asking for your content to be published.
|
| |
jflory7
commented 3 years ago
This commit reorganizes the ROOT module index.adoc page to include a
Table of Contents and also some "frequently sought pages", like how to
create and publish a new Fedora Docs site.
This commit also reworked some of the "Adding new docs" page. I followed
the one sentence per line convention and imported the partials from the
ROOT module for things like mailing list URLs.
This commit was tested and confirmed to work locally. Should be ready to
merge but wouldn't mind a peer review.