Docs Development

This repo is tracking the development of several projects related to Fedora Docs (2.0? .next? reboot?). None of it is official work of the Fedora Project, yet.

This is all in one repo and kind of a "hot mess." This is because we have no end-to-end testing yet so it should be easier to keep it all building together and then tease it apart later when it matures.

Test Module/Assembly Repository

This is to test some topic based building ideas. The ideas are centered on how to have modules and build them into assemblies. For some details on the language, pending some meta-documentation getting committed here, see this thread.

Sources / Work

• assemblies : Directory of user story assemblies
• modules : Directory of discrete standalone text elements
• modules-assemblies-docs : Documentation

Multi-Repository asciibinder

asciibinder doesn't support multiple source repositories, this work extends asciibinder with a preprocessor.

Sources/Work

• _collections_map.yml : yaml file to drive the multi-repository preprocessor
• builder.sh : original bash version of the preprocessor. Includes non-ruby implemented Zanata updates
• multi_ascii_binder.rb : Ruby version of the preprocessor

Localization

Work needs to be done on loading AsciiDoc into Zanata and getting localized text back. The builder.sh developed for the multi-repository asciibinder work does this in a rough way. This needs to be extended. The current solution relies on po4a No work has been done since builder.sh.

• Because asciibinder stores display titles in both _distro_map.yml and _topic_map.yml the solution needs to account for these
• One idea is to do a preprocessor that replaces these values based on values drawn from AsciiDoc sources - this would work for _topic_map.yml

DocBook2AsciiDoc

Moving to AsciiDoc will require a one-time conversion of Fedora Docs materials from DocBook to AsciiDoc. If the material is not rewritten in modules immediately, it'd be great to have a way of doing this with some automation so that it is less work and can get done faster. This automation will also help others and provide us with some test material for localization (see above).

Notes/Ideas

• https://github.com/emmanuelbernard/docbook2asciidoc
• https://github.com/asciidoctor/docbookrx

Implementing ElasticSearch

We need a search solution and elastic seems to be the way to go. One idea is to use the sitemap.xml produced by asciibinder to feed an elastic instance. No work has been done.

Automated Publishing

Ideally we will get both CI and CD in the future.

Continuous Deployment (CD)

• Build and publish on every commit to master:
  • Fedora Jenkins job has been created but is not yet running - ping bexelbie for details
  • This is modeled in work going on for Budget.next
• Build stage branches - no work done.

Continuous Integration (CI)

• Test every PR before merging - no work done.
• Build forked branches to allow writers to see their work before submitting a PR - no work done.

Implementing asciibinder

Using asciibinder to build the site has a lot of potential. It is also used by several other projects giving us a larger community base to build on.

Open Questions:

• Deep Linking across documents is messy today, whether you use link or xref you have to reference an html file. How does OpenShift solve this?
• How can we regenerate just part of a site?
• Should the menu depth be extended to another level or two?
• How can we pass a set of shared attribute definitions to every file processed? (i.e. handling the shared-content attribute)

Sources/Work

• _distro_map.yml : Configuration File
• _topic_map.yml : Configuration File
• _images
• _javascripts
• _stylesheets
• _templates
• index-en-US.html

Other Files

• LICENSE.txt
• README.adoc