Adding a docs build preview to Fileshare - RedHatInsights/red-hat-ansible-automation-platform-documentation GitHub Wiki

Adding a docs build preview to Fileshare

This article describes how to do the following:

  • Copy a built AAP document from a local /build directory to a directory in your Fileshare instance.

  • Identify a link to your directory on Fileshare so that stakeholders can see a preview of your document.

Your Fileshare instance

To request a Fileshare instance, create a ticket in service-now. For an example, see this ticket.

When you are allocated a Fileshare instance, IT allocates space on a server to you and updates your ticket with a message indicating the Fileshare server (host) where your instance is located: 

Your homedir at file.emea host is created

Your Fileshare space is located in <username>@<fileshare_server>:

  • <fileshare_server> refers to the server where your Fileshare instance is, for example file.rdu.redhat.com. In the example service-now message above, the fileshare server is file.emea.redhat.com.

  • <username> is your Kerberos ID, for example ariordan or lmodemal.

The examples below show the process for copying docs to the space allocated to ariordan in the file.emea.redhat.com Fileshare server.

Setting up a directory for your built docs in Fileshare

  1. Connect to the VPN.

  2. Use the following command connect to the Fileshare server:

    $ ssh <username>@<fileshare_server>

    Enter your Kerberos password.

  3. If you are using Fileshare for the first time, you must create a directory called public_html:

    $ mkdir public_html

  4. Navigate to the /public_html directory. Files and subfolders in this directory are viewable by Red Hat associates.

    [ariordan@file01 ~]$ pwd
    /home/remote/ariordan
[ariordan@file01 ~]$ cd public_html

  5. Create a directory in /public_html directory for your preview doc. It’s useful to include the doc title and the date in the directory name. This is not a requirement, but it is good practice to delete obsolete docs from your Fileshare instance.

    [ariordan@file01 ~]$ mkdir <preview_directory>
    [ariordan@file01 ~]$ mkdir aap-on-azure-220308

    You do not have to create a new directory every time you want to copy files to Fileshare.

  6. Exit from the ssh session:

    [ariordan@file01 ~]$ exit
logout
Connection to file.emea.redhat.com closed.

Copying your built docs to Fileshare

  • If you use bccutil to build your docs, the build is located in the /build directory in your title directory.

  • If you use asciidoctor to build your docs, the built doc (master.html) is located in your title directory.

Copying the contents of a /build directory to Fileshare

  1. Connect to the VPN.

  2. Navigate to the directory in /titles that contains the main master.adoc file for the doc that you want to build.

    $ cd titles/aap-on-azure

  3. Build the docs locally. The built docs are in the /build directory.

    $ ls
aap-on-azure attributes   build        docinfo.xml  images       master.adoc

  4. Copy the contents of the /build directory to Fileshare:

    $ scp -r build/ <username>@<fileshare_server>:public_html/<preview_directory>
    $ scp -r build/ [email protected]:public_html/aap-on-azure-220308

    Enter your Kerberos password.

  5. To view the built docs on Fileshare, open one of the following URLs in a browser. Two URLs are listed here, because the destination directory in the Fileshare server can be inconsistent. Sometimes, the`scp` command copies the contents of /build to Fileshare. Other times, the full /build directory is copied to fileshare. `+ http://<fileshare_server>/~<username>/<preview_directory>/tmp/en-US/html-single/ http://<fileshare_server>/~<username>/<preview_directory>/build/tmp/en-US/html-single/

    http://file.emea.redhat.com/~ariordan/aap-on-azure-220308/tmp/en-US/html-single/
http://file.emea.redhat.com/~ariordan/aap-on-azure-220308/build/tmp/en-US/html-single/

    If you can’t locate your build on Fileshare, open your Fileshare home directory in a browser and click the directory names to navigate to the build.

    http://<fileshare_server>/~<username>/<preview_directory>
    http://file.emea.redhat.com/~ariordan/aap-on-azure-220308

Copying master.html to Fileshare

  1. Connect to the VPN

  2. Navigate to the directory in /titles that contains the the doc that you want to build.

    $ cd titles/aap-on-azure

  3. Build the docs locally. The built doc is in master.html.

    $ ls
aap-on-azure attributes   master.html        docinfo.xml  images       master.adoc

  4. Copy master.html to Fileshare:

    $ scp -r master.html <username>@<fileshare_server>:public_html/<preview_directory>
    $ scp -r master.html [email protected]:public_html/aap-on-azure-220308

    Enter your Kerberos password.

  5. To view the built docs on Fileshare, open the following URL in a browser:

    http://<fileshare_server>/~<username>/<preview_directory>/master.html
    http://file.emea.redhat.com/~ariordan/aap-on-azure-220308/master.html

Example output for SSH to Fileshare

$ ssh [email protected]
[email protected]'s password:
Last login: Wed Mar  2 09:37:53 2022 from 10.33.36.182

   **  **  **  **  **  **  **  **  **  **  **  **  **  **  **  **  **  **

               This is a Private Computing System Network.

    This system is for use only by authorized users.  If you do not have
    authorization, discontinue use at once.

    Your use of this system, and all information or communications stored
    on or transmitted to or through it by you, with or without authority,
    or in excess of your authority, is subject to review, monitoring, and
    recording by system personnel, without notice or permission.  Any
    information or data thus obtained by system personnel also is subject
    to review by law enforcement and judicial officials in connection with
    the investigation or prosecution of possible criminal activity
    involving the system.  If you now continue use of the system, you
    expressly consent to these conditions of use.

   **  **  **  **  **  **  **  **  **  **  **  **  **  **  **  **  **  **

   NOTE: This server is under puppet control!  Local changes may be lost.

OS:   RedHat 6.10 2.6.32-754.43.1.el6.x86_64
Env:  (env: prod) (area: ams2)
HW:   (manufacturer: Red Hat) (product: RHEV Hypervisor)
[file01.intranet.prod.int.ams2.redhat.com] [13:25:50-0500]
[ariordan@file01 ~]$

Example output for copying master.html to Fileshare

$ scp -r index.html [email protected]:public_html/docs/spare
[email protected]'s password:
index.html                                    100%   78KB 239.5KB/s   00:00

Example output for copying /build to Fileshare

The example output for this command has been truncated.

$ scp -r build/ [email protected]:public_html/aap-on-azure-march-01
[email protected]'s password:
publican.cfg                                                                                                                              100%  338     4.7KB/s   00:00
master.ent                                                                                                                                100%  189     1.9KB/s   00:00
aap-on-azure-architecture.png                                                                                                             100%  252KB 315.7KB/s   00:00
icon.svg                                                                                                                                  100% 2644    31.0KB/s   00:00
master.xml                                                                                                                                100%   60KB 573.3KB/s   00:00
aap-on-azure-architecture.png                                                                                                             100%  252KB 391.2KB/s   00:00
icon.svg                                                                                                                                  100% 2644    46.6KB/s   00:00
master.xml                                                                                                                                100%   60KB 257.0KB/s   00:00
aap-on-azure-architecture.png                                                                                                             100%  252KB 377.9KB/s   00:00
dir_black.css                                                                                                                              100% 1502    23.6KB/s   00:00
overpass_bold-web.eot                                                                                                                     100%   34KB 116.1KB/s   00:00

Resources

A Google doc by Dayle Parker describes how to copy your built docs to Fileshare.

⚠️ **GitHub.com Fallback** ⚠️