Adding New Docs
This section explains how to create and publish new documentation to the official website→ HPC. Ensure to review all the prerequisites listed in → Getting Started page before you start.
Software Requirements
-
Writers need to install the following software packages for your OS running in your local machine.
Name |
Download URL |
Git |
|
Node Js |
Clone the Repository
Make sure that the SSH key is set up between your local machine and the remote GitLab Server. Refer to the page → Setting Up GitLab on how to connect and setup SSH keys. |
-
URLs for docs-ui and docs-site GitLab repositories.
Folder
GitLab URL
docs-ui
docs-site
-
To clone the repository using SSH, follow the below steps.
-
In the GitLab repository, select Clone and then copy the Clone with SSH URL.
-
Then, type the following command in your local machine.
Syntax :
git clone <clone with SSH URL>
-
To add new docs to the website, only the docs-site repository is required. |
Install the project dependencies
Switch to the cloned docs-site folder in your local machine and run the make build command to install the dependencies for the project
cd docs-site
docs-site$ make build
Also, there are other useful make commands for the project. From the project root, run make to see the list of available options. |
Using Git & Creating Branch
Once all the dependencies are installed, create your own branch and start writing the docs in AsciiDoc Format. To learn more about branches, committing files and Git commands, refer to → Git commands for HPC documentation
Preview site
To preview the site with the changes which you have made, run the make preview command. This launches a live preview of the website in your local machine.
docs-site$ make preview
Output:
+ gulp
[17:01:02] Using gulpfile ~/Desktop/hpc/docs/docs-site/gulpfile.js
[17:01:02] Starting 'default'...
[17:01:02] Starting 'build'...
[17:01:07] Finished 'build' after 5.08 s
[17:01:07] Starting 'preview'...
[Browsersync] Access URLs:
-------------------------------------
Local: http://localhost:3000
External: http://172.20.20.20:3000
-------------------------------------
UI: http://localhost:3001
UI External: http://localhost:3001
Go to → http://localhost:3000 to preview the site in your local PC
Publish new UI changes to docs-site
New UI changes can be incorporated into the docs-site. Refer to the section → How to bundle UI with gulp? to make new UI bundle. Then, copy and paste the generated ui-bundle.zip
file from docs-ui/build
folder → docs-site/ui
folder.
docs-site |_ ui |_ ui-bundle.zip