git checkout -b my-new-docs
)gem install bundler
) are installedbundle
)
bundle install --path vendor/bundle
)npm install
)You're ready to make some changes to the documentation!
.
├── _api/ # Auto-generated API documentation - don't edit by hand!
├── _faq/ # Various FAQ pages
├── _includes/ # Jekyll snippets (headers, footers, etc.)
├── _layouts/ # Jekyll layouts (overall page structure)
├── _tutorials/ # Tutorials / How-to Articles
│ ├── src/ # Docco source files for "side-by-side" tutorials
│ ├── *.html # Auto-generated docco tutorials - don't by edit by hand!
│ ├── *.md # Newer markdown tutorials
├── css/ # Stylesheets (SCSS)
├── examples/ # Raw javascript examples of jasmine tests (rare)
├── pages/ # Various documentation pages
Note the auto-generated files _api/**
and _tutorials/*.html
, don't edit these files as any
changes you make to them will be lost the next time the documentation is generated.
First, update the jasmine API docs:
bundle exec rake update_edge_jasmine
bundle exec rake update_edge_jasmine_npm
, and/or
bundle exec rake update_edge_jasmine_browser
as appropriatenpm run jsdoc
to update the API documentationThen, regenerate the tutorials:
bundle exec rake tutorials
Now preview your changes locally:
bundle exec rake serve
cp -r _api/edge _api/4.4
_api/<new version>/global.html>
, _npm-api/Jasmine.html
,
and/or _browser-runner-api/module-jasmine-browser-runner.html
. The sort key
should be a string with three digits for the major and minor versions, e.g.
"004.003" for version 4.3.prereleaseFor
tag (e.g. prereleaseFor: "5.0"
) to every generated HTML page for the new
version. This will prevent it from being treated as the current version and
add the correct banner to each page.archived: true
to
_api/<old version>/global.html>
, _npm-api/Jasmine.html
, and/or
_browser-runner-api/module-jasmine-browser-runner.html
. This will remove the
version from the listing on the docs home page. It will still be published at
the same URLs and can still be reached through the Archived Documentation link.git commit -am 'Add some docs'
)git push origin my-new-docs
)If you're making complicated or potentially controversial changes to the documentation, it may make sense to provide a live demo that the reviewer can use to compare side-by-side with the current production site.
From the terminal in your local fork of jasmine.github.io
, create the branch gh-pages
:
git checkout master
git checkout -b gh-pages
git push -u origin HEAD
Next, enable GitHub Pages for your fork:
Settings
linkGitHub Pages
header, select Source
-> gh-pages branch
https://<username>.github.io/jasmine.github.io/
Now that you've configured your live demo link to show the gh-pages
branch, you can
update what is shown at any time by resetting that branch to your newest changes. For example,
if you've just pushed up the branch my-complicated-change
, update your live demo
by entering the following in your terminal:
git checkout gh-pages
git reset --hard my-complicated-change
git push -f
Wait a few minutes, and you live demo will now be showing your changes in the my-complicated-change
branch. You can then include a link to the demo in your pull request.