{"id":28452718,"url":"https://github.com/juliasmoothoptimizers/jsotutorials.jl","last_synced_at":"2025-07-08T05:41:32.483Z","repository":{"id":45299494,"uuid":"219565113","full_name":"JuliaSmoothOptimizers/JSOTutorials.jl","owner":"JuliaSmoothOptimizers","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-14T14:23:50.000Z","size":9522,"stargazers_count":5,"open_issues_count":24,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-06T18:12:27.394Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JuliaSmoothOptimizers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-04T18:07:14.000Z","updated_at":"2024-12-14T14:23:53.000Z","dependencies_parsed_at":"2024-12-14T15:24:10.889Z","dependency_job_id":"1b1adeb9-3fb9-4cbf-8b9c-ec7e4befb582","html_url":"https://github.com/JuliaSmoothOptimizers/JSOTutorials.jl","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JuliaSmoothOptimizers/JSOTutorials.jl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JuliaSmoothOptimizers%2FJSOTutorials.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JuliaSmoothOptimizers%2FJSOTutorials.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JuliaSmoothOptimizers%2FJSOTutorials.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JuliaSmoothOptimizers%2FJSOTutorials.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JuliaSmoothOptimizers","download_url":"https://codeload.github.com/JuliaSmoothOptimizers/JSOTutorials.jl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JuliaSmoothOptimizers%2FJSOTutorials.jl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262351519,"owners_count":23297633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-06T18:12:28.787Z","updated_at":"2025-06-27T23:31:39.829Z","avatar_url":"https://github.com/JuliaSmoothOptimizers.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSO Tutorials\n\nCurated repository of tutorials regarding all things JSO.\nSee the renderer tutorials in \u003chttps://jso.dev\u003e.\n\n## Development\n\nAll tutorials are in the `tutorials` folder, inside at least an additional folder.\nIn most cases there is a single `index.jmd`, although it should be possible to have multiple tutorials under the same folder.\n\nThe most important part of the folders is that they should have their own `Project.toml`, i.e., they are Julia environments.\nSo, to develop a new tutorial, create the folder, and open Julia on the folder (you can check that you are in the correct place using `pwd()`.)\n\n### Creating the environment\n\nAssuming you are in the correct folder with the Julia REPL open, press `]` to enter `pkg` mode, and enter `activate .` to activate the environment. Then, you can add the necessary packages for your tutorial.\nAfter the packages are added, the `Project.toml` file should be created.\n\n**Do not to add Weave!** See the building section below.\n\n### Tutorial header\n\nThe tutorial `.jmd` file should have a header like the following:\n\n```yaml\ntitle: \"Title of the tutorial\"\ntags: [\"tag1\", \"tag2\"]\nauthor: \"One Author and Other Author\"\n```\n\n**Please add sufficient tags**.\n\n### Building and previewing locally the tutorial\n\nDuring the development of the tutorial, you will probably want to rerun an rebuild the tutorial several times.\nTo do that, you should\n\n- **open Julia in the root folder of JSOTutorials.jl**,\n- `pkg\u003e activate .`\n- `pkg\u003e instantiate`\n- `julia\u003e using JSOTutorials`\n- `JSOTutorials.weave_file(folder, file)`.\n\nFor reasons that are not entirely clear, `folder` should be the folder **without the tutorials/ prefix**.\nFor instance, I can call `JSOTutorials.weave_file(\"create-a-manual-model\", \"index.jmd\")`.\n\nThis will generate a `markdown/create-a-manual-model/index.md` file, which you can preview, for instance, using VSCode.\n\n### If you want to check the end result (optional)\n\nThe parsed file (contained in `markdown/`) is not exactly what will be sent to the website, because of the Franklin format expected.\nTo fix it, we actually run a separate script.\n\n**You don't have to do this step.**\n\nThe final version will be generated when your code is accepted in the `main` branch, and this is automatic.\n\nThat being said, if are doing some fixes or improvements on this step - or are just curious - then you can do so by running in the shell, the following command:\n\n```shell\nbash .github/workflows/build_tutorial.sh tutorials/create-a-manual-model/index.jmd\n```\n\nThis will run the same `weave_file` command that we used before, and the function `JSOTutorials.parse_markdown_into_franklin`, creating a file inside the folder `parsed/`.\n\nThis function does a few magic things:\n\n- It parses the YAML header and transforms into a Franklin header.\n- It changes output fenced code to type `plaintext`.\n\nAnd it can possibly do more in the future.\n\n### Creating your Pull Request\n\nIf you haven't create a fork, do so now.\n\nIf you cloned your repository, then `origin` will refer to your fork, so you can use `origin` instead of `myfork` below.\n\nIf you cloned `JSOTutorials` from JSO, then you have to add your repository and a git remote.\nDo so with the following command:\n\n```shell\ngit remote add myfork https://github.com/YOURUSER/JSOTutorials.jl\n```\n\nNow, create a branch, commit, and push.\n\n```shell\ngit checkout -b some-tutorial\ngit add tutorial/some-tutorial\ngit commit -am \"New tutorial: Some Tutorial\"\ngit push -u myfork some-tutorial\n```\n\n\u003e If you had an error of some kind here, and you think this explanation can be improved, please create an issue, open a Pull Request, or get in touch.\n\nNow go to \u003chttps://github.com/JuliaSmoothOptimizers/JSOTutorials.jl\u003e and create a pull request.\n\n## Guidelines\n\n- File and folder names should be `lower-case-separated-by-dashes` (AKA kebab-case);\n- Don't forget to add Project.toml, but don't add Manifest.toml.\n\n## Not discussed\n\nThe following topics were not included in the short documentation above for lack of time. **You can help by contributing**.\n\n- The other functions inside JSOTutorials.\n- Generating other kinds of outputs.\n- Converting from Jupyter or Pluto notebooks to the Weave format.\n- Online preview.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuliasmoothoptimizers%2Fjsotutorials.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuliasmoothoptimizers%2Fjsotutorials.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuliasmoothoptimizers%2Fjsotutorials.jl/lists"}