AsciiBinder-Based Fedora Docs Publishing Repo

This is the build repository for the Fedora Documentation Website

Please report Issues and submit Pull Requests for Publishing Fixes here. Content issues be reported against the source repositories:

Testing your changes locally

To test your changes, first install asciibinder

$ sudo dnf install ruby-devel
$ gem install ascii_binder

To build your changes, from the root directory:

$ asciibinder package
$ ./builder.sh
$ firefox _package/main/index.html

How to Publish

Publishing uses two repos:

Pre-requisities

  1. You need git and asciibinder.
    $ gem install ascii_binder
    $ sudo dnf install git
  2. You need both repositories
    $ git clone ssh://git@pagure.io/fedora-docs/docs-fp-o.git
    $ git clone ssh://git@pagure.io/fedora-docs/fedora-docs-web.git

Publishing

  1. Go to the docs-fp-o repository and ensure you are on master and that it is up-to-date
    $ cd <path to="" docs-fp-o="">
    $ git checkout master
    $ git pull
  2. Prepare the repo to be built by loading in all documentation sources.
    $ ./builder.sh

    This will generate a whole lot of output.

  3. Build the site
    $ asciibinder package

    This will also generate a lot of output.

  4. Stage the site
    $ cp -r _package/main/* <path to="" fedora-docs-web="">
    $ cd <path to="" fedora-docs-web="">
    $ git checkout stg
    $ git add .
    $ git commit -m "Updating site"
    $ git push
  5. Review the staged site at docs.stg.fedoraproject.org and see if it looks good. The site is updated approximately every 5 minutes, so give it time.

  6. If you're happy, push the changes to production.
    $ git checkout prod
    $ git merge stg
    $ git push
  7. Verify your changes have gone live at docs.fedoraproject.org and see if they look good. The production site is refreshed once per hour so this may take some time.

Branching New Releaess

In each content repository (i.e. https://pagure.io/fedora-docs/install-guide):

  1. Go to the master branch
    $ git checkout master
  2. Branch for the new release, Fedora 27 in this example:
    $ git checkout -b f27
  3. Update the entities file to reflect the correct version numbers
    $ vi en-US/entities.adoc
  4. Commit your changes and push to the upstream repository
    $ git add en-US/entities.adoc
    $ git commit -m "Branching for F27"
    $ git push upstream f27
  5. Return to the master branch
    $ git checkout master
  6. Update the _distro_map.yml file to add the new version
    $ vi _distro_map.yml
  7. Commit your changes and push to the upstream repository
    $ git add _distro_map.yml
    $ git commit -m "Branching for F27 - updating _distro_map.yml"
    $ git push upstream master

In this repo, the builder repository:

Note: In the build directory the beta version is always in the beta/ directory when published.

  1. Edit the _distro_map.yml to reflect the addition of the new version. See the fXX-en-US lines:

  2. Edit builder.sh to add the new branch to the BRANCHES variable

  3. Edit build.sh to add a new variable to hold the list of content repositories for the new branch. See f26_BOOKS for an example.

  4. Edit the index-main.html to link to the new version, as needed.

Notes

The asciibinder command will incorrectly report that there are nonexistent topics in the _topic_map.yml. This is error is caused by ruby's Find module not following symlinks and is specific to this build repository. To validate a specific content set, test it with asciibinder in its source repository.

Project Plan

Add new features

  • remove builder.sh as new functionality arrives in asciibinder
  • Translations
  • Search
  • CI/CD for automatic publishing and rebuild
  • CI/CD for branch and topic publishing and rebuild
  • ???