How to generate Semantic UI offline doc

Question

It's been a long time I dident generate the docs (since 0.19.3 ), and it seems that the doc was separated.

I dont know how to generate the docs, because it is not well explained:

Before running server you will need to build your UI files for the docs. Semantic UI includes a special command to build files for a docs instance that must be run from an adjacent Semantic UI folder. for example with a directory vendor -> SemanticUI place docs folder inside vendor to reflect vendor -> SemanticUI | docs

Can you please guide me how to do it?

From the Semantic UI source, i run npm install , it installed all what needed, and then when I run gulp build-docs it generated a docs folder which is outside the source, this one, if i run inside it the command docpad run, I dont get the right HTML, because I dont know where to put the Separated Docs downloaded.

Answer 1

Answered here

Just pick what you're missing to get it complete. (It probably has some typos.)

A terminal is required.

Assumed folder structure:

path/to/your/bull polished/project
 |
 `_ docs
 |
 `_ learn
 |
 `_ ui

N.B.

All 3 subfolders docs, learn, ui may be given different names. Subfolders docs and ui must be adjacent folders.

At the moment learnsemantic.com (learn) is independent of the other 2 repos. So it could be placed anywhere you like.

Clone the repos:

cd path/to/your/bull polished/project

docs:

git clone --recursive --progress -v "git@github.com:Semantic-Org/Semantic-UI-Docs.git" "docs"
Cloned https://github.com/Semantic-Org/Semantic-UI-Docs (http://semantic-ui.com/)

learn:

git clone --recursive --progress -v "git@github.com:Semantic-Org/Learn-Semantic.git" "learn"
Cloned https://github.com/Semantic-Org/Learn-Semantic (http://learnsemantic.com/)

ui:

git clone --recursive --progress -v "git@github.com:Semantic-Org/Semantic-UI.git" "ui"
Cloned https://github.com/Semantic-Org/Semantic-UI (The Semantic UI framework)

N.B.

When you don't want to clone all the SUI repo history, read this : #220 (comment)

Install Gulp globally AND locally.

npm install -g gulp
cd "path/to/your/bull polished/project/ui"
npm install gulp

Install the Semantic UI framework.

(Still in : "path/to/your/bull polished/project/ui")

npm install
gulp

OR:

gulp install

Install Docpad globally AND locally. Install Docpad plugins locally.

Install globally:

npm install -g docpad

Note: To update globally docpad upgrade

Then install locally into docs:

cd "path/to/your/bull polished/project/docs"
npm install docpad
docpad install eco

Then install locally into learn:

cd "path/to/your/bull polished/project/learn"
npm install docpad
docpad install eco

Note: To update locally (docpad and plugins) run: docpad update inside the docs and learn folders.

NB

docpad update purges/obliterates the docs/out folder (which was filled with dist and src folders, and files by gulp build-docs, gulp-serve-docs, and docpad run) So when the time comes, run docpad update before building the Docs from the ui folder. Run npm install docpad as root/Administrator (to avoid permission issues).

Definitely on Windows.

Sometimes also on Linux/OS X, if Node was installed "incorrectly". But at least on Linux/OS X you can reinstall Node to correct this. See: node-forward/help#4

Build the Semantic UI framework:

cd "path/to/your/bull polished/project/ui"
Only if required:

gulp clean
Followed by:

gulp build OR gulp watch

Build the Semantic UI framework for the Documentation in the docs folder:

cd "path/to/your/bull polished/project/ui"

gulp build-docs OR gulp serve-docs gulp build-docs : Creates and fills docs/out/dist and docs/out/src gulp serve-docs : Watches for source file changes in the ui folder and updates folders docs/out/dist and docs/out/src.

Generate the Semantic UI Documentation pages and start the local server:

cd "path/to/your/bull polished/project/docs"
docpad run
docpad run : Creates all documentation files and folders (other than docs/out/dist and docs/out/src) in the docs/out folder.

Generate the learnsemantic.com pages and start the local server:

cd "path/to/your/bull polished/project/learn"
docpad run
docpad run : Creates all documentation files and folders in the learn/out folder.

When you're changing the SUI framework variables, etc

1) Make your changes to the framework.

2) Rebuild the framework:

gulp clean (only when necessary)
gulp build OR gulp watch

3) Update the docs: gulp build-docs OR gulp serve-docs

4) Generate the documentation pages. docpad run OR docpad server

Go back to 1)

If you used gulp watch and gulp serve-docs you should be fully automatic.