Over the past week, I set up some HTML generation code and a deployment script on Anarki that creates this documentation page based on Anarki's (help ...) information.
There are several more things I should explain about this:
-
===== What information a help entry is based on =====
Sometimes, some help information is populated while other information isn't available. For instance, right now `list` has everything help.arc is designed to display except for a docstring:
arc> (help list)
[fn] (list . args)
list is not documented.
Examples:
arc> (list 1 2 3)
(1 2 3)
arc> (list "a" '(1 2) 3)
(a (1 2) 3)
nil
arc> (src list)
(from "arc.arc")
(def list args args)
nil
It has a signature ('args), an implementation definer ('def), an implementation body ('args), a source file ("arc.arc"), and examples ('((list 1 2 3) (1 2 3) (list "a" '(1 2) 3) ("a" (1 2) 3))), and of course a value that has a type ('fn), but it has no docstring.
When the code in build-web-help.arc generates the HTML page, it determines whether to display a help entry purely by whether it has a docstring or not. I figure this is a good way to distinguish between things that are interesting to read about and things that are idiosyncratic helper functions, but one consequence is that there is no entry displayed for `list` right now.
-
===== Broken links =====
When the documentation refers to another entry by [[foo]], it's converted to an link to the relevant entry on the page. If there is no entry by that name on the page, it's instead converted to a span of style "broken-link", which shows up in red. If you'd like to fill in gaps in the documentation, you can view the source of the page to find all the occurrences of "broken-link".
-
===== Security of repository access privileges =====
The script pushes to Anarki's gh-pages repo using a personal access token for my GitHub machine user, rocketniabot. I just created rocketniabot for this purpose. The token is limited to pushing to rocketniabot's public repos, and right now the only public repo rocketniabot has access to is Anarki. If this changes in the future, I might want to ask someone else if they can use an access token. (And if no one wants to volunteer one, it's not the end of the world; we'll just stop having automatic pushes to the `gh-pages` branch until it's fixed again.)
The token is not committed to the repo; it's set up in the Travis CI settings as a so-called "encrypted environment variable," which is only exposed during a non-pull-request build or a pull request build that comes from another branch in the same repo. I believe this prevents non-contributors from accessing the token.
Although people could make rocketniabot look bad by having it push abusive content to the `gh-pages` branch, they would first have to either push a build script that exposes the token or push content like that to the `master` branch themselves.
If we notice either of those kinds of abuse occurring, I recommend we take two actions:
- Remove that contributor from the Anarki project on GitHub so they can't keep doing this.
- Please let me know so I can revoke the compromised rocketniabot access token.
- Until I do that, remove the rocketniabot contributor from the Anarki project.
- If you'd like to set up automatic `gh-pages` pushes again and I'm not responding to messages, then I recommend you choose another user account who's willing to be responsible for the automatic pushes, have that account set up a personal access token with public repo access, and put that token in the Travis CI configuration instead. (If you do this, please change the variable name so it's not "ROCKETNIABOT_GH_TOKEN". I think we need to keep track of whose it is so we can notify the right person when it's compromised.)
-
===== Security of the website's client-side data =====
If we ever have any page on the arclanguage.github.io domain store client-side data (like localStorage entries or cookies), someone could potentially access this information and take advantage of it before they're removed from the project. Because of this, I recommend we don't store any client-side data on that domain.
To perhaps start a discussion instead of just leaving a comment: where should we go next with the self-documenting / exploratory code ideas? What's missing or frustrating about the current help system?
