{"id":21293130,"url":"https://github.com/criteo/socco","last_synced_at":"2025-07-11T16:32:15.076Z","repository":{"id":57718516,"uuid":"89678069","full_name":"criteo/socco","owner":"criteo","description":"A Scala compiler plugin to generate documentation from Scala source files.","archived":false,"fork":false,"pushed_at":"2021-10-18T11:25:37.000Z","size":71,"stargazers_count":20,"open_issues_count":0,"forks_count":4,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-04-13T05:52:23.451Z","etag":null,"topics":["documentation","scala","scaladoc"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/criteo.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}},"created_at":"2017-04-28T07:06:05.000Z","updated_at":"2024-02-15T14:20:03.000Z","dependencies_parsed_at":"2022-09-02T11:00:12.674Z","dependency_job_id":null,"html_url":"https://github.com/criteo/socco","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criteo%2Fsocco","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criteo%2Fsocco/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criteo%2Fsocco/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criteo%2Fsocco/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/criteo","download_url":"https://codeload.github.com/criteo/socco/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225741166,"owners_count":17516895,"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","scala","scaladoc"],"created_at":"2024-11-21T13:53:29.856Z","updated_at":"2024-11-21T13:53:30.375Z","avatar_url":"https://github.com/criteo.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Socco\n\nSocco is a Scala compiler plugin to generate documentation from Scala source files.\n\nIt produces HTML documents that display your comments alongside your code. Comments are passed through Markdown, and the Scala code is syntax highlighted, typed and linked to the appropriate API Doc.\n\n## Examples\n\nHere are a few examples generated by Socco. The source .scala files can be found in [examples/src/main/scala](examples/src/main/scala).\n\n1. [Statefully transforming streams with fs2](https://criteo.github.io/socco/examples/fs2Example.scala.html).\n2. [Parsing JSON with circe](https://criteo.github.io/socco/examples/userStyle1/circeExample.scala.html). Using a custom stylesheet.\n3. [Scala collections tour](https://criteo.github.io/socco/examples/userStyle2/collectionsExample.scala.html). Abusing the model to produce a more classical documentation 🙀.\n\n## Usage\n\nIf you use SBT, add the following settings to enable the plugin:\n\n```scala\nautoCompilerPlugins := true\naddCompilerPlugin(\"com.criteo.socco\" %% \"socco-plugin\" % \"0.1.6\")\n```\n\nIf you are using scalac directly, add the following option:\n\n```sh\n-Xplugin:com.criteo.socco.socco-plugin_2.12-0.1.6.jar\n```\n\nThis can be followed by any of the available options:\n\n* `-P:out:$outDir` to specify the output directory.\n* `-P:style:$stylesheetPath` to specify a custom stylesheet.\n* `-P:packagge_$packageName:$scalaDocUrl` to specify a Scala API doc to link.\n* `-P:header:$headerPath` to specify a custom HTML header.\n* `-P:footer:$footerPath` to specify a custom HTML footer.\n\n## Syntax\n\nThe plugin will handle all scala source files starting with a comment line like:\n\n```\n// Example: (.*)\n```\n\nThe captured group will be used as the example title in the generated HTML documents.\n\nThe comments can use markdown syntax, and will be correctly rendered to the generated documentation.\n\nAlso, there is a special kind of comment:\n\n```\n// @className\n```\n\nWhen added on top of a code block, it will add the CSS class to the generated block. Allowing you to style it further wit CSS.\n\n## Prior art\n\n* [Docco](https://jashkenas.github.io/docco/) generates this kind of layout for coffeescript code. It has been ported to several other languages.\n* [Tut](https://github.com/tpolecat/tut) is a documentation tool that allow to embed (and compile) scala code into Markdown documents. Which is exactly the opposite of Socco 😛.\n* [SXR](https://github.com/sbt/sxr) is Scala compiler plugin that turn source code into syntax highlighted and browsable HTML documents. It is outdated now but was a good source of inspiration for socco.\n\n## License\n\nThis project is licensed under the Apache 2.0 license.\n\n## Copyright\n\nCopyright © Criteo, 2017.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcriteo%2Fsocco","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcriteo%2Fsocco","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcriteo%2Fsocco/lists"}