Merge pull request #101 from QURIresearch/hotfix-readme
Hotfix `README.md`s, with a couple piggybacked changes
This commit is contained in:
Ozzie Gooen
GitHub
commit
9886d332d9
6
.github/ISSUE_TEMPLATE/developer-bug.md
vendored
6
.github/ISSUE_TEMPLATE/developer-bug.md
vendored
|
|
@ -1,13 +1,13 @@
|
|||
---
|
||||
name: Developer friction when contributing to Squiggle
|
||||
about: Did your yarn scripts fail? Did the CI diverge from a README? Etc.
|
||||
labels: 'ops'
|
||||
about: Did your yarn scripts fail? Did the CI diverge from a README? Have a testing-related task? Etc.
|
||||
labels: 'ops & testing'
|
||||
---
|
||||
# Description:
|
||||
|
||||
|
||||
# The OS and version, yarn version, etc. in which this came up
|
||||
|
||||
_delete this section if testing task_
|
||||
|
||||
# Desired behavior
|
||||
|
||||
|
|
|
|||
13
.github/ISSUE_TEMPLATE/pl.md
vendored
Normal file
13
.github/ISSUE_TEMPLATE/pl.md
vendored
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
name: Regarding the programming language
|
||||
about: Interpreter, parser, syntax, semantics, and including distributions
|
||||
labels: 'programming language'
|
||||
---
|
||||
- [ ] Is refactor
|
||||
- [ ] Is new feature
|
||||
- [ ] Concerns documentation
|
||||
|
||||
# Description of suggestion or shortcoming:
|
||||
|
||||
|
||||
|
||||
9
.github/workflows/ci.yaml
vendored
9
.github/workflows/ci.yaml
vendored
|
|
@ -1,6 +1,11 @@
|
|||
name: Squiggle packages check
|
||||
|
||||
on: [push]
|
||||
on:
|
||||
push: # Delete this line if there becomes a scarcity of build minutes.
|
||||
pull_request:
|
||||
branches:
|
||||
- master
|
||||
- staging
|
||||
|
||||
jobs:
|
||||
|
||||
|
|
@ -61,7 +66,7 @@ jobs:
|
|||
- uses: actions/checkout@v2
|
||||
- name: Install dependencies from monorepo level
|
||||
run: cd ../../ && yarn
|
||||
- name: Build rescript in squiggle-lang
|
||||
- name: Build rescript codebase in squiggle-lang
|
||||
run: cd ../squiggle-lang && yarn build
|
||||
- name: Run webpack
|
||||
run: yarn bundle
|
||||
|
|
|
|||
|
|
@ -34,9 +34,10 @@ We use netlify, and it should only concern Quinn, Sam, and Ozzie.
|
|||
|
||||
You need `yarn`.
|
||||
|
||||
TODO: fill this out based on all the different packages scripts once they cool down.
|
||||
Being a monorepo, where packages are connected by dependency, it's important to follow `README.md`s closely. Each package has it's own `README.md`, which is where the bulk of information is.
|
||||
|
||||
We aspire for `ci.yaml` and `README.md`s to be in one-to-one correspondence.
|
||||
|
||||
# Pull request protocol
|
||||
|
||||
Please work against `staging` branch. **Do not** work against `master`. Please do not merge without approval from some subset of Quinn, Sam, and Ozzie; they will be auto-pinged.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,6 +2,12 @@
|
|||
|
||||
This is an experiment DSL/language for making probabilistic estimates. The full story can be found [here](https://www.lesswrong.com/s/rDe8QE5NvXcZYzgZ3).
|
||||
|
||||
## Our deployments
|
||||
|
||||
- **website/docs prod**: https://squiggle-language.com
|
||||
- **website/docs staging**: https://staging--squiggle-documentation.netlify.app/
|
||||
- **old playground**: https://playground.squiggle-language.com
|
||||
|
||||
This monorepo has several packages that can be used for various purposes. All
|
||||
the packages can be found in `packages`.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Squiggle language
|
||||
|
||||
# Build for development
|
||||
## Build for development
|
||||
We assume that you ran `yarn` at the monorepo level.
|
||||
``` sh
|
||||
yarn build
|
||||
|
|
@ -15,75 +15,21 @@ yarn test
|
|||
yarn test:watch # keeps an active session and runs all tests at every mutation
|
||||
```
|
||||
|
||||
# TODO: clean up this README.md
|
||||
## Information
|
||||
Squiggle is a language for representing probability distributions, as well as functions that return probability distributions. Its original intended use is for improving epistemics around EA decisions.
|
||||
|
||||
# Squiggle Language
|
||||
Squiggle is a language for representing probability distributions, as well as
|
||||
functions that return probability distributions. Its original intended use is
|
||||
for improving epistemics around EA decisions.
|
||||
This package, `@quri/squiggle-lang`, contains the core language of squiggle. The main feature revolves around evaluating squiggle expressions. Currently the package only exports a single function, named "run", which from a squiggle string returns an object representing the result of the evaluation.
|
||||
|
||||
This package, @quri/squiggle-lang, contains the core language of squiggle. The main
|
||||
feature revolves around evaluating squiggle expressions. Currently the package
|
||||
only exports a single function, named "run", which from a squiggle string returns
|
||||
an object representing the result of the evaluation.
|
||||
If using this package for tests or as a dependency, typescript typings are available and recommended to be used.
|
||||
|
||||
If using this package for tests or as a dependency, typescript typings are available
|
||||
and recommended to be used.
|
||||
This package is mainly written in [ReScript](https://rescript-lang.org/), but has a typescript interface.
|
||||
|
||||
## Building this package
|
||||
This package doesn't have any dependencies on any other packages within the monorepo,
|
||||
so if you wish you can generally ignore lerna or yarn workspaces when dealing
|
||||
with this package in particular.
|
||||
ReScript has an interesting philosophy of not providing much in the way of effective build tools. Every ReScript file is compiled into `.bs.js` and `.gen.ts` files with the same name and same location, and then you can use these files in other `.js` files to create your program. To generate these files to build the package, you run `yarn build`.
|
||||
|
||||
First, as per any node package, you will need to install dependencies, we recommend
|
||||
using [yarn](https://classic.yarnpkg.com/en/).
|
||||
`.gen.ts` files are created by the [`@genType`](https://rescript-lang.org/docs/gentype/latest/getting-started) decorator, which creates typescript typings for needed parts of the codebase so that they can be easily used in typescript. These .gen.ts files reference the .bs.js files generated by rescript.
|
||||
|
||||
```bash
|
||||
yarn
|
||||
```
|
||||
|
||||
This package is mainly written in [ReScript](https://rescript-lang.org/). But has
|
||||
a typescript interface.
|
||||
|
||||
ReScript has an interesting philosophy of not providing much in the way of effective
|
||||
build tools. Every ReScript file is compiled into .bs.js and .gen.ts files with the same name
|
||||
and same location, and then you can use these files in other js files to
|
||||
create your program. To generate these files to build the package, you run
|
||||
`yarn build`.
|
||||
|
||||
```bash
|
||||
yarn build
|
||||
```
|
||||
|
||||
.gen.ts files are created by [genType](https://rescript-lang.org/docs/gentype/latest/getting-started),
|
||||
which creates typescript typings for needed parts of the codebase so that they
|
||||
can be easily used in typescript. These .gen.ts files reference the .bs.js files
|
||||
generated by rescript.
|
||||
|
||||
You can also go `yarn start` for the purposes of watching for file changes and
|
||||
rebuilding every time there is one.
|
||||
|
||||
Finally, `yarn test` runs the current test suite over the language.
|
||||
|
||||
You may notice sometimes, that there are errors about the `rationale` package.
|
||||
If you ever get these errors, `yarn build` should fix this issue. These errors
|
||||
occur because `yarn build` also needs to create build files that are in `node_modules`.
|
||||
So if you replace `node_modules` you may need to rebuild to get those files back.
|
||||
### Errors regarding the `rationale` package
|
||||
You may notice sometimes, that there are errors about the `rationale` package. If you ever get these errors, `yarn build` should fix this issue. These errors occur because `yarn build` also needs to create build files that are in `node_modules`. So if you replace `node_modules` you may need to rebuild to get those files back.
|
||||
|
||||
## Distributing this package or using this package from other monorepo packages
|
||||
If you would like to distribute this package, run `yarn package` to compile all the js
|
||||
and typescript into the `dist` directory. This `dist` directory code is what's
|
||||
referenced by other packages in the monorepo.
|
||||
|
||||
## Using this package
|
||||
The return type of this packages only experted function `run` is currently quite
|
||||
complicated, as it has to return either a number, or a distribution, or even
|
||||
a representation of a function of distributions. Currently the export is simply
|
||||
the generated type that rescript creates, and can be quite confusing. We therefore
|
||||
highly recommend the use of typescript when creating tests or using this package.
|
||||
|
||||
## Potential Issues
|
||||
If you experiment with generating different types of .gen.ts files and similar, note that they won't be caught by git (because they are in .gitignore). Make sure you delete these extra files, once they are unecessary.
|
||||
```
|
||||
rm src/rescript/**/*.gen.ts
|
||||
```
|
||||
As it says in the other `packages/*/README.md`s, building this package is an essential step of building other packages.
|
||||
|
|
|
|||
|
|
@ -2,34 +2,27 @@
|
|||
|
||||
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
|
||||
|
||||
### Installation
|
||||
## Build for development and production
|
||||
|
||||
This one actually works without running `yarn` at the monorepo level, but it doesn't hurt. You must at least run it at this package level
|
||||
|
||||
``` sh
|
||||
yarn
|
||||
```
|
||||
|
||||
### Local Development
|
||||
|
||||
``` sh
|
||||
yarn start
|
||||
```
|
||||
|
||||
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
|
||||
|
||||
### Build
|
||||
|
||||
This command generates static content into the `build` directory and can be served using any static contents hosting service.
|
||||
``` sh
|
||||
yarn build
|
||||
```
|
||||
|
||||
This command generates static content into the `build` directory and can be served using any static contents hosting service.
|
||||
Your local dev server is here, opening up a browser window.
|
||||
``` sh
|
||||
yarn start
|
||||
```
|
||||
|
||||
### Clean
|
||||
Most changes are reflected live without having to restart the server.
|
||||
|
||||
Clean up the build artefacts.
|
||||
``` sh
|
||||
yarn clean
|
||||
```
|
||||
|
||||
# TODO: unify formatting across `packages/*/README.md`
|
||||
# TODO: build docs in `ci.yaml`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user