{"id":20169590,"url":"https://github.com/hwayne/alloydocs","last_synced_at":"2025-04-09T10:05:23.017Z","repository":{"id":43360897,"uuid":"254207817","full_name":"hwayne/alloydocs","owner":"hwayne","description":"Proposed documentation for alloytools.org","archived":false,"fork":false,"pushed_at":"2024-11-12T22:34:09.000Z","size":309,"stargazers_count":71,"open_issues_count":5,"forks_count":17,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-02T08:51:25.128Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hwayne.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2020-04-08T21:46:56.000Z","updated_at":"2025-03-11T13:03:04.000Z","dependencies_parsed_at":"2024-11-12T23:33:16.490Z","dependency_job_id":null,"html_url":"https://github.com/hwayne/alloydocs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwayne%2Falloydocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwayne%2Falloydocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwayne%2Falloydocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwayne%2Falloydocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hwayne","download_url":"https://codeload.github.com/hwayne/alloydocs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248018060,"owners_count":21034048,"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":"2024-11-14T01:13:10.641Z","updated_at":"2025-04-09T10:05:22.991Z","avatar_url":"https://github.com/hwayne.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alloydocs\n\nThis is the repository for development of the [Alloy](http://www.alloytools.org/) documentation. The documentation is currently hosted [here](https://alloy.readthedocs.io/en/latest/index.html) and the source lives [here](https://github.com/hwayne/alloydocs). This readme is for people who are interested in building and contributing it.\n\n## Building\n\n\nThe docs currently run on Sphinx. You can install Sphinx with [these instructions](https://www.sphinx-doc.org/en/master/usage/installation.html). You will also need the theme:\n\n```\npython -m pip install sphinx-rtd-theme\n```\n\nDocs can be built with ``make html``. Single file PDF version can be built with ``make latexpdf`` (requires LaTeX installed).\n\n## Development\n\nThe repo is [standard Sphinx](https://www.sphinx-doc.org/en/master/intro.html), using reStructured Text. Some things might use a bit too much rst as I was getting a feel for what worked and didn't here.\n\nThere are two customizations:\n\n### Custom Alloy Domain\n\nUnder `utils/alloy.py`. It has roles for functions, predicates, and properly indexes them. Sphinx's standard \"this is a function\" flag will add parens to docs, while Alloy uses brackets. So we make the brackets part of the function title and then split them off while indexing.\n\n**TODO:** To speed up writing documentation I added an `:also:` param to functions that have \"obvious\" analogs. For example:\n\n```rst\n.. als:predicate:: lt[e1, e2: elem]\n\n  :also: ``gt``, ``lte``, ``gte``\n\n  True iff ``e1 in prevs[e2]``.\n```\n\nFunctions defined in `:also:` don't have cross-references or indexes. We should change that.\n\n**TODO:** Currently the `alloy.py` is pretty rickety and should be cleaned up/made more idiomatic.\n\n### advanced class\n\nSome sections are marked as \"Advanced\":\n\n```rst\n.. rst-class:: advanced\n.. _enums:\n\nEnums\n-----\n```\n\nAdvanced sections have an indicator before them, currently `[⋇] `, that marks them as unnecessary for beginners to learn. I have two **TODOs** I want to add:\n\n1. A tooltip saying \"this is an advanced section\" so people know what it means without having read the intro\n1. A button that toggles whether the advanced sections are visible at all\n\n\n## Other Misc Tasks\n\n* The reference currently isn't comprehensive.\n* Cross references are a bit inconsistent. Some are hyphen-cased, some use spaces. Both are valid, but I'd like to move everything to hyphens for consistency.\n* The location of certain topics might move around.\n* There are many todos in the docs. These are not visible in the \"proper\" version, but are there for internal discussion.\n\n## Contributing\n\nTODO\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhwayne%2Falloydocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhwayne%2Falloydocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhwayne%2Falloydocs/lists"}