{"id":13723293,"url":"https://github.com/erszcz/docsh","last_synced_at":"2025-10-07T01:30:18.098Z","repository":{"id":57490923,"uuid":"50245799","full_name":"erszcz/docsh","owner":"erszcz","description":"Erlang Docs in the Shell predating EEP-48 and shell_docs","archived":true,"fork":false,"pushed_at":"2023-11-23T08:50:25.000Z","size":5540,"stargazers_count":120,"open_issues_count":8,"forks_count":8,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-10-01T15:07:58.723Z","etag":null,"topics":["documentation","elixir","erlang","repl"],"latest_commit_sha":null,"homepage":"","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erszcz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2016-01-23T16:04:31.000Z","updated_at":"2024-09-12T12:37:34.000Z","dependencies_parsed_at":"2024-01-10T21:01:47.527Z","dependency_job_id":"7378bd16-2b88-427b-889e-d900239423d9","html_url":"https://github.com/erszcz/docsh","commit_stats":{"total_commits":526,"total_committers":6,"mean_commits":87.66666666666667,"dds":"0.011406844106463865","last_synced_commit":"2fc09e93d6541eb014b464081d14a8490eecdba3"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erszcz%2Fdocsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erszcz%2Fdocsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erszcz%2Fdocsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erszcz%2Fdocsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erszcz","download_url":"https://codeload.github.com/erszcz/docsh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235569500,"owners_count":19011184,"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","elixir","erlang","repl"],"created_at":"2024-08-03T01:01:38.700Z","updated_at":"2025-10-07T01:30:17.691Z","avatar_url":"https://github.com/erszcz.png","language":"Erlang","funding_links":[],"categories":["Erlang Specific","Erlang"],"sub_categories":[],"readme":"# ARCHIVED\n\n`docsh` was a prototype of a documentation system for the Erlang shell,\ninspired by languages like Python, Ruby, or Elixir,\nin which docs are first class elements of the language.\n\nIt predated Erlang/OTP 23, which was the first release to\ninclude [`shell_docs`](https://www.erlang.org/doc/man/shell_docs)\nauthored by @garazdawi.\n\nFor Erlang/OTP 24 I (@erszcz) contributed a new feature to Erlang's EDoc:\n[emitting EEP-48 style doc chunks][edoc_chunks],\nwhich can be consumed by `shell_docs` or [ExDoc](https://github.com/elixir-lang/ex_doc).\n\nIf you want to document an Erlang Rebar3 project with ExDoc or generate doc chunks for it,\ncheck out @starbelly's neat\n[rebar3_ex_doc](https://github.com/starbelly/rebar3_ex_doc) plugin!\n\nThese ecosystem changes make `docsh`, the prototype, obsolete, so I'm archiving this repo.\nI'm really happy, though, that the idea spearheaded by this project caught on!\n\n[edoc_chunks]: https://www.erlang.org/doc/apps/edoc/chapter#Doc_chunks\n\n# Docs in the Shell\n\n[![TravisCI Build Status](https://travis-ci.org/erszcz/docsh.svg?branch=master)](https://travis-ci.org/erszcz/docsh)\n[![Hex version badge](https://img.shields.io/hexpm/v/docsh.svg)](https://hex.pm/packages/docsh)\n\nStill can't remember if it's `(Tab, Key)` or `(Key, Tab)` in `ets:lookup/2`?\nWhat about `gb_trees:lookup/2`? Hint: it's not the same!\nEver wished for access to function signatures and documentation straight from `erl`\nthe way it's possible in languages like Python, Ruby or Elixir?\n\n[![docsh - light and dark background](https://raw.githubusercontent.com/erszcz/docsh/master/doc/light-dark-bg.png)](https://github.com/erszcz/docsh/blob/master/doc/light-dark-bg.png)\n\n\n## Use in Rebar3 shell\n\nAdd these lines to your `rebar.config`:\n\n```erlang\n{plugins,\n [\n  {rebar3_docsh, \"0.7.2\", {pkg, docsh}}\n ]}.\n{shell, [{script_file, \"_build/default/plugins/rebar3_docsh/priv/docsh_rebar3_shell.escript\"}]}.\n```\n\n`rebar3 shell` will now have a set of new helpers to access docs. Start with `h(docsh)`.\n\nNote: This will dynamically compile and load a `user_default` module shipped with docsh.\nIt will override your own `user_default` if you use one.\n\n\n## Use in `erl`\n\n```\ngit clone https://github.com/erszcz/docsh\ncd docsh\n./install.sh\n```\n\nThe script will ask if you're sure you want to create some\nErlang configuration files:\n\n```\n$ ./install.sh\n\nInstalling docsh\n\nThis install script will make docsh globally available in your\nuser environment.\nIt will install the following files:\n\n  /Users/erszcz/.erlang\n  /Users/erszcz/.erlang.d/user_default.erl\n\nTo know more about these files please refer to:\n\n  man erl - sections about 'The .erlang startup file'\n            and 'user_default and shell_default'\n  man shell_default - parts about user_default\n\nDo you want to proceed? [y/N]\n```\n\nEven if you agree to install, but the target files exist,\nit won't proceed - don't worry if you have customized your\nErlang environment already.\n\nOnce the installation is complete,\n`erl` will greet you in a bit different way than you might be used to:\n\n```erlang\n$ erl\nErlang/OTP 19 [erts-8.2] [source] [64-bit] [smp:4:4] [async-threads:10] [kernel-poll:false]\n\nEnabled docsh from: /Users/erszcz/work/erszcz/docsh\nEshell V8.2  (abort with ^G)\n1\u003e\n```\n\n\n## Access docs in the shell\n\nLet's see what docsh can give us for some OTP modules.\nWe call `h/2` to get the doc for `lists:keyfind` no matter the arity:\n\n```\n$ erl\nErlang/OTP 19 [erts-8.2] [source] [64-bit] [smp:8:8] [async-threads:10] [hipe] [kernel-poll:false]\n\nEnabled docsh from: /Users/erszcz/work/erszcz/docsh/_build/default/lib/docsh\nCall h(docsh) for interactive help.\n\nEshell V8.2  (abort with ^G)\n1\u003e h(proplists).\n\n# proplists\n\nSupport functions for property lists.\n\nProperty lists are ordinary lists containing entries in the form\nof either tuples, whose first elements are keys used for lookup and\ninsertion, or atoms, which work as shorthand for tuples {Atom,\ntrue}. (Other terms are allowed in the lists, but are ignored\nby this module.) If there is more than one entry in a list for a\ncertain key, the first occurrence normally overrides any later\n(irrespective of the arity of the tuples).\n\nProperty lists are useful for representing inherited properties,\nsuch as options passed to a function where a user may specify options\noverriding the default settings, object properties, annotations,\netc.\n\n% @type property() = atom() | tuple()\n\nok\n2\u003e t(proplists).\n-type property() :: atom() | tuple().\n-type proplist() :: [property()].\nok\n3\u003e\n```\n\nLet's try with Recon:\n\n```\ngit clone https://github.com/ferd/recon\ncd recon\n./rebar compile\nerl -pa ebin/\n```\n\nOnce in the Erlang shell:\n\n```erlang\nErlang/OTP 19 [erts-8.2] [source] [64-bit] [smp:8:8] [async-threads:10] [hipe] [kernel-poll:false]\n\nEnabled docsh from: /Users/erszcz/work/erszcz/docsh/_build/default/lib/docsh\nCall h(docsh) for interactive help.\n\nEshell V8.2  (abort with ^G)\n\u003e s(recon_trace, calls).\n\nrecon_trace:calls/2\n\n-spec calls(tspec() | [tspec(), ...], max()) -\u003e num_matches().\n\n\nrecon_trace:calls/3\n\n-spec calls(tspec() | [tspec(), ...], max(), options()) -\u003e num_matches().\n\nok\n\u003e h(recon_trace, calls, 2).\n\nrecon_trace:calls/2\n\n-spec calls(tspec() | [tspec(), ...], max()) -\u003e num_matches().\n\nEquivalent to calls({Mod, Fun, Args}, Max, [])\nSee calls/3\n\nok\n\u003e\n```\n\nAs you can see above, `s/2` gives us just the function specs.\nHaving read them, we want a more detailed description of `recon_trace:calls/2`,\nso we ask for the doc and specify the arity with `h/3`.\n\nTry it with your project!\n\n\n## Embed docs in your modules\n\nMake sure to document your code with EDoc.\nThen add the following to your project's `rebar.config`:\n\n```erlang\n{plugins,\n [\n  {rebar3_docsh, \"0.7.2\", {pkg, docsh}}\n ]}.\n\n{provider_hooks,\n [\n  {post, [{compile, {docsh, compile}}]}\n ]}.\n```\n\n\n[edoc:module-tags]: http://erlang.org/doc/apps/edoc/chapter.html#Module_tags\n[gh:recon-docsh]: https://github.com/erszcz/recon\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferszcz%2Fdocsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferszcz%2Fdocsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferszcz%2Fdocsh/lists"}