node.jsgulpdocpadsemantic-ui

How to generate Semantic UI offline doc

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.

Solution

  • 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.