• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    迪恩网络公众号

uwiger/edown: EDoc extension for generating Github-flavored Markdown

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

uwiger/edown

开源软件地址(OpenSource Url):

https://github.com/uwiger/edown

开源编程语言(OpenSource Language):

Erlang 86.0%

开源软件介绍(OpenSource Introduction):

Edown - Markdown generated from Edoc

Copyright (c) 2014 Ulf Wiger

Authors: ulf@wiger.net.

Status:

More-or-less readable Markdown can be generated. A doclet needs to be written that also creates a markdown-based index and overview. Currently, the edoc_doclet creates an index.html and overview.html, which do not point to the .md files.

To generate markdown edoc, run:


edoc:application(App, [{doclet, edown_doclet} | OtherOpts]).

The edown_xmerl module is used as an xmerl export module. It converts xmerl's "simple xml" to Markdown syntax. Note that GH-flavored Markdown allows HTML markup (at least common tags), but doesn't expand markdown markup inside HTML markup, so the edown_xmerl module has to know the context in which it operates.

Top-level README

Using the option {top_level_readme, {File, BaseHref}}, a github-friendly README.md in the top directory can be generated from the overview.edoc. This file is the same as the doc/README.md file already generated, but with relative links corrected (using BaseHref) so that they actually work. This step is needed since Github doesn't support relative paths in Markdown links.

Example:

{top_level_readme, {"./README.md", "http://github.com/uwiger/edown"}}

The conversion function will fetch the current branch name from git, and fail if it cannot do so.

It is also possible to add the branch information specifically: {top_level_readme, {File, BaseHref, Branch}}, although this shouldn't be necessary as long as edown can derive the branch name from git.

Using Atlassian Stash or Gitlab as target

The option {edown_target, github | stash | gitlab} can be used to control which is the intended host repository. This affects how links are rewritten in order to find related files and stay on the correct branch.

The default value is github.

Note that at the moment, the Markdown viewer plugin will be needed in order to render the generated documentation as Markdown on Stash.

Github customizations

pre tags are converted into github "fenced" code blocks, i.e.

```...'''

. If language-specific syntax highlighting is desired, this can be achieved by adding a 'lang' attribute, e.g.

<pre lang="erlang">
incr(X) ->
  %% This should be formatted with Erlang syntax highlighting
  X + 1.
</pre>

which should format like this:

incr(X) ->
  %% This should be formatted with Erlang syntax highlighting
  X + 1.

Rebar customizations

A set of escripts can be found under edown/priv/scripts/, which can be used to customize the rebar built process. The rebar.config.script file should be copied into your application, next to rebar.config. It will sense if doc is a current target, and will then include edown in the deps; otherwise, it removes it. This way, you will not have to pull down edown unless you really want to build the docs. It will also locate edown along your path, in which case it doesn't need to pull it down again.

The script will also start the inets application, so that you can include URLs as part of a doc_path option (see below).

Links to other EDown-generated docs

There is a way to configure Edoc/Edown to get URLs right even when linking to other Edown-generated docs on Github.

First, you need to specify paths to the edoc-info files for each repository as part of edoc_opts in your rebar.config, e.g.

   {doc_path, ["http://raw.github.com/uwiger/setup/master/doc",
               "http://raw.github.com/uwiger/gproc/master/doc"]}

Note (1) that we use "http:://...", not "https://...", since Edoc doesn't recognize the latter. Also note that we use URLs to the raw files. This is for Edoc as it fetches the edoc-info files. Edown will detect and rewrite such links in the generated output, since "raw" links wouldn't work for the markdown files.

The next issue is that Edoc uses httpd_client to fetch the edoc-info files, which requires inets to be started. To further complicate matters, ssl (and thus crypto, 'asn1' and public_key) must also be started, since Github will redirect to https.

One way to solve this is to use the escripts found under edown/priv/scripts.

NOTE

EDoc provides a plugin structure, so that one may specify own layout modules, export modules, and doclets. However, there is some overlap esp. between the layout and doclet modules, and several functions are expected to produce files on their own. This causes a problem for EDown, since it cannot handle frames. Instead, it would probably like to create one overview file with different sections. It would have been better to have a framework where some plugin functions identify the different files to be written, and the outline of each, other plugins convert to suitable content representation (e.g. HTML or Markdown), and EDoc then writes the files necessary.

For now, EDown focuses on producing reasonable Markdown, rather than complying fully with the plugin framework. That is, the edown_doclet module will not go out of its way to function together with any other layout module than edown_layout, and vice versa.

markedoc

The sed script bin/markedoc works in the opposite direction and converts your README.md to an EDoc file.

See bin/MARKEDOC-README.md.

FreeBSD, Mac OS X$ sed -E -f markedoc.sed <markdown file> > <edoc file>

Linux$ sed -r -f markedoc.sed <markdown file> > <edoc file>

Modules

edown_doclet
edown_layout
edown_lib
edown_make
edown_xmerl



鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
joyent/restdown: Pretty REST API docs authored in Markdown发布时间:2022-08-18
下一篇:
DT27/EditorMD: Markdown 编辑器 Editor.md for Typecho发布时间:2022-08-18
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap