{"id":18446847,"url":"https://github.com/nmeum/scmdoc","last_synced_at":"2025-04-15T02:43:44.213Z","repository":{"id":74907392,"uuid":"586612956","full_name":"nmeum/scmdoc","owner":"nmeum","description":"Automatically generate documentation from comments in R7RS Scheme code","archived":false,"fork":false,"pushed_at":"2024-07-31T22:00:53.000Z","size":287,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-16T12:57:42.968Z","etag":null,"topics":["documentation","documentation-generator","documentation-tool","r7rs","r7rs-scheme","r7rs-small"],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nmeum.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":"2023-01-08T18:38:51.000Z","updated_at":"2024-07-31T22:00:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"d2c76517-348e-4d6a-b5c1-bd5b5e7ed4f9","html_url":"https://github.com/nmeum/scmdoc","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeum%2Fscmdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeum%2Fscmdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeum%2Fscmdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeum%2Fscmdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nmeum","download_url":"https://codeload.github.com/nmeum/scmdoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248997080,"owners_count":21195787,"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":["documentation","documentation-generator","documentation-tool","r7rs","r7rs-scheme","r7rs-small"],"created_at":"2024-11-06T07:11:01.117Z","updated_at":"2025-04-15T02:43:44.196Z","avatar_url":"https://github.com/nmeum.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Demo\n\nA sample documentation for [chibi parse][chibi parse] is available: https://files.8pit.net/scmdoc-demo/\n\n## Motivation\n\nTooling for inline source code documentation of Scheme code is rare.\nExisting tools like [chibi-doc][chibi-doc source] actually interpret/load the code and thus do not work if, for example, some utilized libraries are not available for `chibi-scheme`.\nTo overcome this limitation `scmdoc` takes a different approach were the code is not interpreted and only parsed.\nThis allows `scmdoc` to be applicable to different R⁷RS implementations ([CHICKEN][chicken web], [Guile][guile web], [Gambit][gambit web], [Racket][racket r7rs], …) as long as the input is syntactically valid R⁷RS.\nPattern matching is then performed on parsed S-expressions to format them nicely in the generated documentation (e.g. matching for procedure definitions, library definitions, …).\nIn its essence, `scmdoc` is therefore a glorified pattern matcher for S-expressions.\n\n## Status\n\nThis is currently a proof-of-concept.\nThe R7RS parser should support the majority of the standard but is not well tested.\nA HTML generation backend is available and several R7RS expressions are formatted at the moment, including more complex ones like record type definitions.\n\n## Installation\n\nThis software is known to compile with GHC 9.4.4 and can be installed by running the following commands inside the repository:\n\n    $ cabal install\n\n## Tests\n\nUnit tests are available and can be invoked using the following command:\n\n    $ cabal test\n\nFurthermore, integration tests are available.\nThese tests require the `scmdoc` binary to be available in your `$PATH`.\nFurthermore, they require [Tidy][tidy web] to be installed.\nIf these prerequisites are satisfied run the following command to execute these tests:\n\n    $ ./golden/run.sh\n\n## Approach\n\nThe `scmdoc` tool is structured around R7RS Scheme libraries.\nFor a given Scheme source file, it extracts all library declaration which are prefixed by a doc comment.\nContrary to a normal Scheme comment, a doc comment has the form `;;\u003e`.\nAs such, `scmdoc` would for example recognize the following library declaration:\n\n    ;;\u003e My awesome scheme library\n    (define-library (sample-library)\n        …)\n\nFor each recognized library, `scmdoc` expands all includes in the declaration and then extracts all exported and documented expressions from the library.\nThe recognized expressions are then further processed by high-level formatters which recognize S-expressions constituting Scheme procedure definitions et cetera.\nThese formatters are available in `src/SchemeDoc/Format` and essentially perform pattern matching on arbitrary S-expressions.\nFor example, the formatter for Scheme procedure definitions roughly looks as follows:\n\n    mkProcedure :: Sexp -\u003e Maybe Procedure\n    mkProcedure (List ((Id \"define\"):(List ((Id defid):arglst)):bodylst)) =\n        -- Convert the S-expression into an algebraic data structure\n        -- which represents Scheme Procedure definitions and can be\n        -- formated.\n    mkProcedure _ = Nothing\n\nIn the future, it should be possible to also supply custom formatters to, for example, to generate documentation for definitions defined using custom macros.\nApart from formatters, `scmdoc` also has a WiP concept of \"expanders\" which perform primitive comment-preserving macro expansion.\nThis feature is presently used to expand record type definitions (`define-record-type`) to primitive procedure definitions which are then formatted using the procedure formatter.\n\n## Usage\n\nThe `scmdoc` tool generates HTML from a Scheme input defining a R7RS library.\nAs described above, only documented S-expressions for which a documentation formatter is available are included in the generated documentation.\nIn order to demonstrate generation of HTML documentation consider the following input file called `library.scm`:\n\n    ;;\u003e This is my documented library.\n    (define-library (math arithmetic)\n      (export my-proc my-magic-constant)\n\n      ;; This is a normal comment which is not considered by scmdoc.\n      (begin\n        ;;\u003e this is a hidden helper function which is not exported.\n        (define my-mult *)\n\n        ;;\u003e my-proc multiplies the given value with two.\n        (define (my-proc x)\n          (my-mult x 2))\n\n        ;;\u003e A magic constant.\n        (define my-magic-constant 42)))\n\nIn order to generate HTML documentation, using `scmdoc`, for this library run the following command:\n\n    $ scmdoc library.scm\n\nWithin documentation comments, it is possible to use Markdown markup.\n\n### Section Comments\n\nDue to the lack of type information, it is difficult to meaningfully group Scheme program components.\nFor this reason, `scmdoc` relies on manually inserted *section comments* for grouping.\nA section comment is a documentation comment which starts with a `|` character and is followed by an empty line and a normal documentation comment.\nThe section comment corresponds to the section title, the documentation comment following it functions as the section description.\nFor example:\n\n    ;;\u003e| Multiplication Procedures\n    ;;\u003e\n    ;;\u003e Procedures for performing multiplication.\n\n    ;;\u003e Multiply two signed values.\n    (define (multS x y) …)\n\n    ;;\u003e Multiply two unsigned values.\n    (define (multU x y) …)\n\nThis will group the procedure `multS` and `multU` into the section *“Multiplication Procedures”*.\nEvery section comment consists of a section title (as indicated by `;;\u003e|`) and a mandatory section description.\nEach documented Scheme library *should* contain at least one section comment.\nIf the Scheme library doesn't contain any section comments, then everything is grouped under an arbitrary “Declarations” section.\n\n### Look and Feel\n\nThe HTML generated by `scmdoc` should be compatible with any [classless CSS framework][cssbed web].\nBy default, the [water.css][water.css web] dark theme is used.\nA custom CSS stylesheet can be specified using the `--stylesheet` command-line.\nFor more information on classless CSS frameworks refer to [this blog post][greenfield classless].\n\n## Related Work\n\nA loose, incomplete collection of similar work on the documentation of Scheme code:\n\n* [Scribble][scribble web]: The documentation tool used by the Racket programming language\n* [chibi-doc][chibi-doc source]: The documentation tool used by chibi-scheme (inspired by Scribble)\n* [SchemeDoc][schemedoc web]: Extract documentation from Scheme comments using [LAML][laml web]\n* MOLE: [Scheme Program Source Code as a Semistructured Data][mole paper]\n* [`l2t`][l2t web] (aka. LiSP2TeX): A literate programming utility for inserting Scheme into TeX files\n* [schemeweb][schemeweb ctan]: Simple literate programming for Scheme with LaTeX\n\n## Development\n\nPlease format all code with [fourmolu](https://github.com/fourmolu/fourmolu).\nFor convince, a pre-commit Git hook for checking if files are properly formated is provided in `.githooks`.\nIt can be activated using:\n\n    $ git config --local core.hooksPath .githooks\n\n## License\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation.\nFurthermore, this code presently includes the Scheme number parser from [Husk Scheme][husk-scheme github] which is licensed under MIT.\n\n[chicken web]: https://call-cc.org\n[guile web]: https://www.gnu.org/software/guile/\n[gambit web]: https://www.gambitscheme.org/\n[racket r7rs]: https://pkgs.racket-lang.org/package/r7rs\n[chibi-doc source]: https://github.com/ashinn/chibi-scheme/blob/master/tools/chibi-doc\n[husk-scheme github]: https://github.com/justinethier/husk-scheme\n[schemedoc web]: https://people.cs.aau.dk/~normark/schemedoc/\n[schemeweb ctan]: https://ctan.org/pkg/schemeweb\n[mole paper]: http://www.schemeworkshop.org/2001/lisovsky.pdf\n[laml web]: http://people.cs.aau.dk/~normark/laml-distributions/laml/\n[l2t web]: https://christian.queinnec.org/WWW/l2t.html\n[scribble web]: https://docs.racket-lang.org/scribble/index.html\n[cssbed web]: https://www.cssbed.com/\n[greenfield classless]: https://ubershmekel.medium.com/the-next-css-frontier-classless-5e66f3f25fdd\n[water.css web]: https://watercss.kognise.dev/\n[chibi parse]: https://synthcode.com/scheme/chibi/lib/chibi/parse.html\n[tidy web]: https://www.html-tidy.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmeum%2Fscmdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnmeum%2Fscmdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmeum%2Fscmdoc/lists"}