layer5io/docs

[Docs] Improve Installation Guide

Closed this issue · 7 comments

nikhilkalburgi commented

Current State

  1. There is no proper guide on which type of Hugo to install standard or extended on windows
  2. On make setup Hugo raises a concern about installing GO

Desired State

Specify to install Hugo Extended and also to install GO with it

OR

Specify to Install GO and Create a npm script like below and add it to Makefile because hugo can be installed as a dev dependency with npm

"setup": "hugo server -D"
"site": "hugo server -D -f"

Also, Change the Makefile as below:

setup:
	npm install
	npm run setup
site:
        npm run site

I have no idea about how it works in other OS. We can discuss it.

Contributor Guides and Resources

leecalcote commented

Let's avoid the npm route. Capturing the fact that a contributor doesn't have Hugo installed and letting them know to install Hugo by pointing them to Hugo's installation instructions is helpful. You can use the same dependency check approach that the Makefile in https://github.com/meshery/meshery/blob/master/Makefile

leecalcote commented

A man of your word, @nikhilkalburgi. 👍 Good of you to jump in.

leecalcote commented

I'm unaware of the difference between Hugo standard and extended. I'll let @iArchitSharma coordinate with you on this topic.

nikhilkalburgi commented

A man of your word, @nikhilkalburgi. 👍 Good of you to jump in.

Thank You

I'll let @iArchitSharma coordinate with you on this topic.

Sure.

iArchitSharma commented

@nikhilkalburgi @leecalcote Docsy works on extended version of HUGO so yes we can specify that on contribution guidelines, Reference

nikhilkalburgi commented

Suggestions from my side:

Changes in Makefile:

## Install docs.layer5.io dependencies on your local machine.
## See https://gohugo.io/categories/installation
setup: 
    -  hugo server -D
    +  npm install

site: + check-go
       hugo server -D -f

## Run docs.layer5.io on your local machine with draft and future content enabled.

.PHONY: setup build site clean site-fast + check-go

+ check-go:
+	@echo "Checking if Go is installed..."
+	@command -v go > /dev/null || (echo "Go is not installed. Please install it before proceeding."; exit 1)
+	@echo "Go is installed."

Changes in Contributing.md:

**Note:** 
1. If you're on a _Windows environment_ then it is highly recommended that you install [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install) both for performance and ease of use.

+ 2. You need to install [Go](https://go.dev/doc/install) before you install Hugo or you will encounter an Error when you build 
    the site using `make site`.

+ 3. If you are installing the pre-built version from [Hugo](https://gohugo.io/) site then ensure that you install the Extended Version Of 
    Hugo.

Problems in the existing guide:

  1. The make setup rule does not install the dependencies mentioned in the package.json instead runs hugo server -D.
  2. The rule make setup raises Go installation Error if Go is not installed by the contributor along with hugo-extended.
  3. If the User installs the standard version of Hugo then it does not come up with sass-dart and causes another error when make setup.

The above (+) suggested changes in guide can help the contributor to troubleshoot the above problems. I have also included the dep-check approach as it is suggested by you @leecalcote

@leecalcote and @iArchitSharma what do you think about these suggested changes? Once you confirm, I can update and raise a PR. 😊

iArchitSharma commented

@nikhilkalburgi please go ahead and raise PR for the make file
For Contributing.md add a Prerequisites section just copy it from docsy Readme