Skip to content

Latest commit

 

History

History
120 lines (73 loc) · 3.47 KB

gsoc.adoc

File metadata and controls

120 lines (73 loc) · 3.47 KB
Raw

GSoC: Improve Uyuni Documentation Publishing Theme

Table of Contents

Project Title

Improve Uyuni Documentation Publishing Theme

Description

Use our existing Antora theme and learn our publishing process for Uyuni documentation. Then with input from our team, design a modern, classy theme that meets Uyuni documentation standards.

Deliverable and Expectations

You will help design and update the frontend for our Uyuni documentation. Several of the following items may be reviewed and customized.

  • Asciidoctor document block styles (Admonitions, paragraphs, tables, positioning, literals, code blocks etc)

  • UI organization and styles (navbar, footer and header)

  • Quality of life improvements using javascript (navbar, google analytics, )

Mentor

Joseph Cayouette

Skills

Native or fluent English, You will need to have a good understanding of Linux, and be comfortable with version control using git and github. You will be working with Asciidoc, so learning the basics of this markdown style will be useful. Antora utilizes the Asciidoctor API to publish static HTML pages from asciidoc sources.

  • Javascript (Required)

  • HTML (Required)

  • CSS (Required)

  • Asciidoc (Basic)

  • YAML (Helpful)

  • Handlebars Templating (Helpful)

  • Skill Level Medium

Getting started

The following information will help you get started.

I have setup a branch in our uyuni-docs repository that we can collaborate from on Gitlab. This repository contains the supplemental overrides for the default-ui for antora.

  • https://github.com/uyuni-project/uyuni-docs/tree/gsoc-uyuni-theme

    1. Clone the repository:

      git clone https://github.com/uyuni-project/uyuni-docs.git

    2. Checkout the gsoc-uyuni-theme branch:

      git checkout gsoc-uyuni-theme

    3. Create your own branch to work from:

      git checkout -b gsoc-uyuni-theme-naman

    4. Navigate to `branding/supplemental-ui/uyuni/uyuni-webui/

    5. Make the desired adjustments to any of the content here. Depending on what you are working on you may need to modify parts of the default-ui. Contact me for this

Workflow

Working with the Default UI

  1. We will not need to do much to the default UI. (We only need adjust basic items here.)

  2. I use nvm to manage my node versions. Once you have nvm installed run nvm install 10

  3. You can switch to this version of Node.js at any time using the following command: nvm use 10

  4. To preview your changes run gulp preview. This sets up a local server so you can preview your changes in real time in your browser.

Working with Supplemental Files

We keep our custom changes to the default ui in our uyuni-docs repo. These are located in: https://github.com/uyuni-project/uyuni-docs/tree/master/branding/supplemental-ui/uyuni/uyuni-webui

There are a few ways of working with the supplemental files:

  1. Build the uyuni-docs site after making your changes, then hit f5 in the Chrome to update make antora-uyuni

  2. You can serve the content from the uyuni-docs/build folder. I use ruby -run -e httpd . -p 5000