Step by Step
It may be useful to run the development docs locally when working on a forked version of semantic, as the docs themselves help in testing out changes to ui components.
1. Install Node
Semantic docs are written in DocPad which requires NodeJS.
There are many tutorials online on how to install node in your environment, here are a few we think are helpful:
2. Fork Semantic
Fork the Semantic repo into a directory on your local machine and navigate into that directory
Alternatively, you can download the entire repository as a zip instead of using Git
3. Install Dependencies
NPM (Node Package Manager) keeps track of all the dependencies required for the project.
Updating npm inside the local directory will grab all development dependencies from package.json and store them in the root of the project.
4a Creating Packages for Server
Additionally your server needs to have the latest version of Semantic built before the documentation will appear formatted correctly. Running grunt build will create a version of the library at docs/build available for your server
4b Watching Files
Docpad will automatically generate a static (html/css only) version of the documentation everytime you update a file inside server/
If you would like it to build semantic everytime you edit a file inside src/ you will have to run the grunt watch script.
4c. Start Your Server
Now that you've installed all the dependencies, starting your server should be a simple command
Docpad should now run the documentation on a local server accessible at http://localhost:9778
A static version of the documentation will be generated every time you make a change to a document. This will also be available in the docs/ folder.
5. (Optional) Install Karma
Unit tests are written in Jasmine, but are run using a test runner called Karma. To install karma you need to grab the npm package.
Installing Karma will allow you to run the unit tests on Javascript to ensure all tests are passed when changes are made to javascript code. This will also occur automatically when you create a pull request
Using Grunt
Watch Changes in Source
If you are working on fixing a UI component that is part of Semantic, your best bet is to work actively on the file in /src/{type}/{elementname}/ while running a watch script from grunt. This will rebuild the docs after you make changes, so you can see if you have corrected the issue you are fixing.
To see exactly what this grunt tasks is doing view our commented gruntfile
The watch task is the default grunt task for Semantic, so you can start it quite simply. This will copy files automatically from the src directory, compiling LESS files, whenever any changes are made.
Run Unit Tests
Tests will automatically run with grunt watch if you have started karma
You can also run the test suite manually
Build Semantic Packages Locally
There is also a separate grunt command for building minified, packaged, and compressed versions of the library. This might be useful when creating custom builds of Semantic.