diff --git a/README.md b/README.md
index c22f92632ab2186f3f6a3e637354360e1321f8a3..772018a381bf03fef2a4220dd6c4affc37a97942 100644
--- a/README.md
+++ b/README.md
@@ -27,9 +27,11 @@ 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.
+but doesn't expand markdown markup inside HTML markup, so the
+`edown_xmerl` module has to know the context in which it operates.
-** Special edown option: **
+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`.
@@ -44,6 +46,23 @@ Example:
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 as target
+-------------------------------
+
+The option `{edown_target, github | stash}` 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](https://bitbucket.org/atlassianlabs/stash-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.
@@ -76,9 +95,9 @@ incr(X) ->
Rebar customizations
====================
A set of escripts can be found under
-[edown/priv/scripts/](http://github.com/esl/edown/blob/master/priv/scripts/), which
+[edown/priv/scripts/](http://localhost:7990/users/uwiger/repos/edown/browse/priv/scripts/?at=refs/heads/uw-stash-links), which
can be used to customize the `rebar` built process. The
-[rebar.config.script](http://github.com/esl/edown/blob/master/priv/scripts/rebar.config.script)
+[rebar.config.script](http://localhost:7990/users/uwiger/repos/edown/browse/priv/scripts/rebar.config.script?at=refs/heads/uw-stash-links)
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
@@ -142,7 +161,7 @@ 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](http://github.com/esl/edown/blob/master/bin/MARKEDOC-README.md).
+See [bin/MARKEDOC-README.md](http://localhost:7990/users/uwiger/repos/edown/browse/bin/MARKEDOC-README.md?at=refs/heads/uw-stash-links).
**FreeBSD, Mac OS X**`$ sed -E -f markedoc.sed <markdown file> > <edoc file>`
@@ -153,9 +172,9 @@ See [bin/MARKEDOC-README.md](http://github.com/esl/edown/blob/master/bin/MARKEDO
<table width="100%" border="0" summary="list of modules">
-<tr><td><a href="http://github.com/esl/edown/blob/master/doc/edown_doclet.md" class="module">edown_doclet</a></td></tr>
-<tr><td><a href="http://github.com/esl/edown/blob/master/doc/edown_layout.md" class="module">edown_layout</a></td></tr>
-<tr><td><a href="http://github.com/esl/edown/blob/master/doc/edown_lib.md" class="module">edown_lib</a></td></tr>
-<tr><td><a href="http://github.com/esl/edown/blob/master/doc/edown_make.md" class="module">edown_make</a></td></tr>
-<tr><td><a href="http://github.com/esl/edown/blob/master/doc/edown_xmerl.md" class="module">edown_xmerl</a></td></tr></table>
+<tr><td><a href="http://localhost:7990/users/uwiger/repos/edown/browse/doc/edown_doclet.md?at=refs/heads/uw-stash-links" class="module">edown_doclet</a></td></tr>
+<tr><td><a href="http://localhost:7990/users/uwiger/repos/edown/browse/doc/edown_layout.md?at=refs/heads/uw-stash-links" class="module">edown_layout</a></td></tr>
+<tr><td><a href="http://localhost:7990/users/uwiger/repos/edown/browse/doc/edown_lib.md?at=refs/heads/uw-stash-links" class="module">edown_lib</a></td></tr>
+<tr><td><a href="http://localhost:7990/users/uwiger/repos/edown/browse/doc/edown_make.md?at=refs/heads/uw-stash-links" class="module">edown_make</a></td></tr>
+<tr><td><a href="http://localhost:7990/users/uwiger/repos/edown/browse/doc/edown_xmerl.md?at=refs/heads/uw-stash-links" class="module">edown_xmerl</a></td></tr></table>
diff --git a/doc/README.md b/doc/README.md
index 5900de1b3f5ee08d5ade55027b8d03418bbbeee3..bf4fc8b40b38f051dcfdf9018ab051f8728c559a 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -27,9 +27,11 @@ 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.
+but doesn't expand markdown markup inside HTML markup, so the
+`edown_xmerl` module has to know the context in which it operates.
-** Special edown option: **
+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`.
@@ -44,6 +46,23 @@ Example:
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 as target
+-------------------------------
+
+The option `{edown_target, github | stash}` 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](https://bitbucket.org/atlassianlabs/stash-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.
diff --git a/doc/overview.edoc b/doc/overview.edoc
index 70737b0af382712f854e40864dcd4e0a00975fb9..7f854732a024e7444c1a7daf91cde8bfac5a5d28 100644
--- a/doc/overview.edoc
+++ b/doc/overview.edoc
@@ -21,10 +21,11 @@ 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
+but doesn't expand markdown markup inside HTML markup, so the
`edown_xmerl' module has to know the context in which it operates.
-** Special edown option: **
+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'.
@@ -40,6 +41,23 @@ Example:
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 as target
+-------------------------------
+
+The option `{edown_target, github | stash}' 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
+<a href="https://bitbucket.org/atlassianlabs/stash-markdown-viewer-plugin">Markdown viewer plugin</a> 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.
diff --git a/make_doc b/make_doc
index c574f966a5710bc08d15236145b051320a3e56ff..810a9e53cc6818faf483f178fc2b0737ff73b28e 100755
--- a/make_doc
+++ b/make_doc
@@ -14,7 +14,7 @@ main([]) ->
false -> Default;
Str -> Str
end,
- TopURL = "http://github.com/" ++ U ++ "/edown",
+ TopURL = top_url(U),
io:fwrite("Making edown docs for [~s]...~n", [TopURL]),
R = edoc:application(edown, ".",
[{doclet, edown_doclet},
@@ -22,6 +22,7 @@ main([]) ->
{app_default,"http://www.erlang.org/doc/man"},
{stylesheet, ""}, % don't copy stylesheet.css
{image, ""}, % don't copy erlang.png
+ {edown_target, target()},
{top_level_readme,
{"./README.md", TopURL}}]),
case R of
@@ -31,3 +32,18 @@ main([]) ->
io:fwrite("~p~n", [Err]),
halt(1)
end.
+
+top_url(User) ->
+ case os:getenv("EDOWN_TOP_URL") of
+ false ->
+ "http://github.com/" ++ User ++ "/edown";
+ URL ->
+ URL
+ end.
+
+target() ->
+ case os:getenv("EDOWN_TARGET") of
+ false -> github;
+ "github" -> github;
+ "stash" -> stash
+ end.
diff --git a/src/edown_doclet.erl b/src/edown_doclet.erl
index 7dfa5b2b5081f8e4178221cc2fcab1668af95ad2..6660cb4dbb34f7457984407365a9444a9cab024c 100644
--- a/src/edown_doclet.erl
+++ b/src/edown_doclet.erl
@@ -168,25 +168,30 @@ make_top_level_README(Data, Options) ->
undefined ->
ok;
{Path, BaseHRef} ->
- Dir = filename:dirname(Path),
- Filename = filename:basename(Path),
- make_top_level_README(Data, Dir, Filename, BaseHRef);
+ Dir = filename:dirname(Path),
+ Filename = filename:basename(Path),
+ make_top_level_README(Data, Dir, Filename, BaseHRef,
+ get_git_branch(), target(Options));
{Path, BaseHRef, Branch} ->
- Dir = filename:dirname(Path),
- Filename = filename:basename(Path),
- make_top_level_README(Data, Dir, Filename, BaseHRef, Branch)
+ Dir = filename:dirname(Path),
+ Filename = filename:basename(Path),
+ make_top_level_README(Data, Dir, Filename, BaseHRef, Branch,
+ target(Options))
end.
-make_top_level_README(Data, Dir, F, BaseHRef) ->
- Branch = get_git_branch(),
- make_top_level_README(Data, Dir, F, BaseHRef, Branch).
+target(Options) ->
+ proplists:get_value(edown_target, Options, github).
-make_top_level_README(Data, Dir, F, BaseHRef, Branch) ->
+%% make_top_level_README(Data, Dir, F, BaseHRef) ->
+%% Branch = get_git_branch(),
+%% make_top_level_README(Data, Dir, F, BaseHRef, Branch).
+
+make_top_level_README(Data, Dir, F, BaseHRef, Branch, Target) ->
Exp = [xmerl_lib:expand_element(D) || D <- Data],
New = [xmerl_lib:mapxml(
fun(#xmlElement{name = a,
attributes = Attrs} = E) ->
- case redirect_href(Attrs, Branch, BaseHRef) of
+ case redirect_href(Attrs, Branch, BaseHRef, Target) of
{true, Attrs1} ->
E#xmlElement{attributes = Attrs1};
false ->
@@ -198,8 +203,9 @@ make_top_level_README(Data, Dir, F, BaseHRef, Branch) ->
Text = xmerl:export_simple_content(New, edown_xmerl),
edoc_lib:write_file(Text, Dir, F).
-redirect_href(Attrs, Branch, BaseHRef) ->
- AppBlob = BaseHRef ++ "/blob/" ++ Branch ++ "/",
+redirect_href(Attrs, Branch, BaseHRef, Target) ->
+ {Prefix, URIArgs} = href_redirect_parts(Target, BaseHRef, Branch),
+ %% AppBlob = BaseHRef ++ "/blob/" ++ Branch ++ "/",
case lists:keyfind(href, #xmlAttribute.name, Attrs) of
false ->
false;
@@ -212,9 +218,10 @@ redirect_href(Attrs, Branch, BaseHRef) ->
nomatch ->
case Href of
[$# | _] ->
- HRef1 = do_redirect(?INDEX_FILE ++ Href, AppBlob);
+ HRef1 = do_redirect(?INDEX_FILE ++ Href,
+ Prefix, URIArgs);
_Else ->
- HRef1 = do_redirect(Href, AppBlob)
+ HRef1 = do_redirect(Href, Prefix, URIArgs)
end,
{true,
lists:keyreplace(
@@ -223,12 +230,18 @@ redirect_href(Attrs, Branch, BaseHRef) ->
end
end.
-do_redirect(Href, Prefix) ->
+href_redirect_parts(github, BaseHRef, Branch) ->
+ {BaseHRef ++ "/blob/" ++ Branch ++ "/", []};
+href_redirect_parts(stash, BaseHRef, Branch) ->
+ {BaseHRef ++ "/browse/", "?at=refs/heads/" ++ Branch}.
+
+
+do_redirect(Href, Prefix, Args) ->
case filename:split(Href) of
[_] ->
- Prefix ++ "doc/" ++ Href;
+ Prefix ++ "doc/" ++ Href ++ Args;
_ ->
- Prefix ++ Href
+ Prefix ++ Href ++ Args
end.
get_git_branch() ->