Skip to content

DafnyPages

Jump to bottom
David Cok edited this page Jul 19, 2022 · 7 revisions

Writing and previewing Dafny on-line user documentation

Dafny on-line documentation is available to users at https://dafny.org. Dafny documentation for developers is on this wiki.

The user documentation is currently mostly resident in the docs folder of the dafny-lang/dafny GitHub project. When the contents of that folder on the master branch is pushed to the shared GitHub repository, then GitHub serves those markdown pages at dafny.org/dafny. (This organization is going to change and will be described more completely then.)

Previewing changes

The user-facing pages are written in GitHub markdown. GitHub only renders them after they are pushed, which requires a PR, review and approval. This is how to preview your edits prior to making a PR.

  • The project workflow is for individual contributors to have their own (team-visible) fork of dafny-lang/dafny.git, from which PRs are created. For a developer named "you", this repo is typically automatically named "you/dafny" (and is at github.com/you/dafny).

  • Make sure that the branch on which you are editing the markdown pages has been pushed to the GitHub repo (the mirror of the local repo in which you are editing) so that the remote copy of the branch exists.

  • If you make edits that should change section numbering, run make numbers in docs/DafnyRef and commit the result before pushing the edits.

  • In the Settings menu for the "you/dafny" repo, on the "Pages" pane (see the list of panes in the sidebar), make these settings under Source:

    • set the branch to whatever branch you are doing your edits on (so you may change this from time to time)
    • set the folder to /docs
    • The theme should be set to "Minima"

  • The rendered HTML pages are visible at "you.github.io/dafny". Changes will be visible once they are pushed via "git push". There can be some delay while the GitHub server realizes there are changes and re-renders the pages. You can watch github.com/you/dafny/actions for runs of an implicit workflow called "pages build and deployment".

  • If there is an error in rendering your pages, it will appear as if nothing has changed or the server is being very slow about refreshing the new content. To see any rendering errors, look at the Actions page of your fork (GitHub.com/you/dafny/actions). You will see there if the latest build action is in progress, successful or failed. If it failed, you can select it to see the errors. For example, a common error that causes a failed build is omitting a newly created file from git's add/commit/push.

  • When you are satisfied with your edits, then make the usual PR and have them reviewed by a teammate. Feel free to include a link to "you.github.io/dafny" so reviewers can review the fully-rendered changes as well!

Clone this wiki locally