Documentation - NetLogo/NetLogo GitHub Wiki

The documentation for NetLogo is also contained in the NetLogo repository. The current online version should always be located here: http://ccl.northwestern.edu/netlogo/docs/

There are three main sources for the docs, one is the templates in autogen/docs. There are HTML and Markdown templates there, corresponding to the pages on the main docs site. There are docs created from the bundled extensions. These use the NetLogo extension documentation plugin to geenrate their README.md files which contain their info. There is also developer API documentation made with Scaladoc.

There are sbt tasks setup in the project/Docs.scala file to generate the HTML docs, pull in the extension docs, generate the PDF user manual, and copy it all into the netlogo-gui/docs folder so it can be referenced during development and deployment.

You can run the allDocs task to generate all the documentation for the project and copy it to the correct location. Generating the PDF manual depends on having wkhtmltopdf installed, as described in Releasing under General dependencies.

Online Docs

At NetLogo release time the docs are copied along with the binary packages. The current ccl.northwestern.edu/netlogo/docs is specified via symlinks to the current NetLogo version, and the version-specific docs can always be accessed in their non-symlink home, such as https://ccl.northwestern.edu/netlogo/5.3.1/docs

The process for updating the symlinks when necessary is in the Releasing page under the Releasing heading. It includes some examples.

In the project/NetLogoPackaging.scala file there is an sbt task called uploadDocs defined, which you can run with dist/uploadDocs. It updates the online docs for the current version of NetLogo after release. It depends on having your USER environment variable set to your CCL server user.

The command releases whatever the current state of the docs are, so if there are new features in the main branch that have new docs added, you cannot use this method. As long as only doc updates or clarifications that are applicable to the current release are involved, then it's okay to use. An easy way to double-check doc changes is by running something like git diff 6.2.0 HEAD autogen/ where 6.2.0 is the current release version tag. You also need to check the bundled extensions haven't had changes as well.

If you need to update the docs but have non-compatible changes, workarounds would be:

• Generate the docs locally and scp them to the server manually. This would be fine for small (single file) changes.
• Add your doc change commits to the latest on the main branch, then make a new branch, revert it to prior to the non-compatible changes, cherry-pick your new changes back on, and then run the upload command. It might be worth adding a permanent tag for this branch just in case if this is ever necessary.