Ocsigen

Home

Doc

Eliom

Js_of_ocaml

Lwt

Tyxml

Start

Contributing to Ocsigen

For individual contributers

To contribute to an Ocsigen project, first see the guidelines it provides. It will give you the directives on how to make your contribution. Once ready, create a Pull Request on the repository and wait for feedback!

Every contribution has to be documented! The documentation is stored on a branch wikidoc. For your contribution to be accepted, you also need to make a PR on that branch for your documentation. On your forked branch, feel free to push and the CI will tell you if your documentation has errors. It will only be deployed to https://ocsigen.org by Travis when merged on wikidoc.

The documentation format is the wikicréole. Please find the reference here. You can generate the documentation of your API directly in Ocsigen's wikicréole using ocamldoc. Do not hesitate to ask for help if you experience any trouble.

Remember, you have to issue 2 pull requests—one for your code on master and one for its documentation on wikidoc—for your contribution to be accepted!

Create a release (for package maintainers)

  1. Make sure the documentation on git branch wikidoc is up to date with the code on master.
  2. On branch wikidoc, cp -r dev X.Y.Z, where X.Y.Z is the new version's number. Commit changes, do a PR, wait for the documentation to be regenerated, and check the documentation on the website.
  3. Update file CHANGES
  4. On master, update opam configuration file.
  5. git tag <version> puis git push --tags
  6. Create a release on GitHub.
  7. opam publish and wait for the package to be accepted.
  1. Add a file in directory _posts of repository ocsigen.github.io on Github to create a blog post that will be published on OCaml Planet and Twitter's OCaml page

Also do not forget to push on wikidoc as it will update the website automatically for the new version.

Local documentation generation

html_of_wiki can (to some extent) locally generate your documentation. Please find its manual here. Each project, on the wikidoc branch, contains a file how.json. Please ensure that its configuration is correct for your changes. The following steps require you to be at the root of the project. 

tmp=$(mktemp -d) && \
git clone --depth 1 https://github.com/ocsigen/ocsigen.github.io.git $tmp && \
mv $tmp/{template,how_template} && \
mv $tmp/how_template .

quickdop -f DOCS _doc -t json -c how.json -viul

If you want to avoid generating the whole documentation—just some parts of it—read the documentation of the tools dop and ohow in the manual of html_of_wiki.

Main site

Changes in the main site must be done in repository ocsigen.github.io, branch master, directory manual. Site generation must be done manually: make deploy.

Generate the whole website locally (experimental)

One can generate the whole website locally using the local-build branch of ocsigen.github.io repo. The branch contains git sub-modules for all projects documented on the website. 

./build.sh _doc