elixir-lang / ex_doc Goto Github PK
View Code? Open in Web Editor NEWExDoc produces HTML and EPUB documentation for Elixir projects
Home Page: http://elixir-lang.org
License: Other
ExDoc produces HTML and EPUB documentation for Elixir projects
Home Page: http://elixir-lang.org
License: Other
defmodule Example do
@type foo(x) :: {x, any}
@type t :: foo(String.t)
end
Creating documentation for this yields a t()
foo()
type with a link to foo()
. It doesn't have a link to String.t()
.
The idea of the docs.all task is to go through all dependencies in a project and generate their documentation inside docs/PROJECT
. Then generate an index file with links to each project and put it in docs/index.html
. This way, developers will have easy access to the documentation of all dependencies in a given project.
In order for this to work, we should also change the default target of the mix docs
task to be docs/PROJECT
.
Crashes with the following error:
** (UndefinedFunctionError) undefined function: Macro.to_string/1
Macro.to_string({:main,0,[{:args,[line: 2],nil}]})
/Users/chee/elixir/issues/deps/ex_doc/lib/templates/detail_template.eex:3: ExDoc.HTMLFormatter.detail_template/1
/Users/chee/elixir/issues/deps/ex_doc/lib/templates/module_template.eex:88: ExDoc.HTMLFormatter."-module_template/6-lc$^5/1-5-"/1
/Users/chee/elixir/issues/deps/ex_doc/lib/templates/module_template.eex:88: ExDoc.HTMLFormatter.module_template/6
/Users/chee/elixir/issues/deps/ex_doc/lib/ex_doc.ex:81: ExDoc.generate_module_page/4
/Users/chee/elixir/issues/deps/ex_doc/lib/ex_doc.ex:75: ExDoc.generate_list/5
lists.erl:1323: :lists.foreach/2
/Users/chee/elixir/lib/elixir/lib/enum.ex:284: Enum.each/2
Is there a reason why ex_doc is not versioned? I'm getting build errors. I suppose I'll have to fork and roll back changes to get a version to compile. Any other suggestions?
Thanks
Autolink erlang functions in the docs (of the form :module.fun/arity
) to the erlang manual pages.
I've almost got a working version of this and will submit a PR soon.
tovmasyan@input255 ~/ex_doc
$ mix test
src/markdown.c:1:0: error: -fPIC ignored for target (all code is position indepe
ndent) [-Werror]
cc1.exe: all warnings being treated as errors
make[1]: *** [src/markdown.o] Error 1
make: *** [sundown/libsundown.so] Error 2
cd sundown && make
make[1]: Entering directory /u/ex_doc/sundown' gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o src/markdo wn.o src/markdown.c make[1]: Leaving directory
/u/ex_doc/sundown'
=ERROR REPORT==== 1-Jul-2013::17:42:14 ===
Error in process <0.73.0> with exit value: {{badmatch,{error,{load_failed,"Faile
d to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├
н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markdo
wn.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:42:14 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
=ERROR REPORT==== 1-Jul-2013::17:42:14 ===
Error in process <0.75.0> with exit value: {{badmatch,{error,{load_failed,"Faile
d to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├
н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markdo
wn.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:42:14 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
=ERROR REPORT==== 1-Jul-2013::17:42:14 ===
Error in process <0.77.0> with exit value: {{badmatch,{error,{load_failed,"Faile
d to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├
н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markdo
wn.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:42:14 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
=ERROR REPORT==== 1-Jul-2013::17:42:14 ===
Error in process <0.85.0> with exit value: {{badmatch,{error,{load_failed,"Faile
d to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├
н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markdo
wn.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:42:14 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
F
=ERROR REPORT==== 1-Jul-2013::17:42:15 ===
Error in process <0.88.0> with exit value: {{badmatch,{error,{load_failed,"Faile
d to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├
н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markdo
wn.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
F
=ERROR REPORT==== 1-Jul-2013::17:42:15 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
=ERROR REPORT==== 1-Jul-2013::17:42:15 ===
Error in process <0.91.0> with exit value: {{badmatch,{error,{load_failed,"Faile
d to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├
н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markdo
wn.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:42:15 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
F
=ERROR REPORT==== 1-Jul-2013::17:42:16 ===
Error in process <0.97.0> with exit value: {{badmatch,{error,{load_failed,"Faile
d to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├
н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markdo
wn.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:42:16 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
F
=ERROR REPORT==== 1-Jul-2013::17:37:27 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
F
=ERROR REPORT==== 1-Jul-2013::17:37:28 ===
Error in process <0.151.0> with exit value: {{badmatch,{error,{load_failed,"Fail
ed to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н
├н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markd
own.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:37:28 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
F
=ERROR REPORT==== 1-Jul-2013::17:37:30 ===
Error in process <0.155.0> with exit value: {{badmatch,{error,{load_failed,"Fail
ed to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н
├н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markd
own.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:37:30 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
F
=ERROR REPORT==== 1-Jul-2013::17:37:31 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
=ERROR REPORT==== 1-Jul-2013::17:37:31 ===
Error in process <0.159.0> with exit value: {{badmatch,{error,{load_failed,"Fail
ed to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н
├н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markd
own.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
F........................
=ERROR REPORT==== 1-Jul-2013::17:37:33 ===
Error in process <0.190.0> with exit value: {{badmatch,{error,{load_failed,"Fail
ed to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н
├н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markd
own.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:37:33 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
F...
=ERROR REPORT==== 1-Jul-2013::17:37:33 ===
Error in process <0.196.0> with exit value: {{badmatch,{error,{load_failed,"Fail
ed to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н
├н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markd
own.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:37:33 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
F
=ERROR REPORT==== 1-Jul-2013::17:37:33 ===
Error in process <0.199.0> with exit value: {{badmatch,{error,{load_failed,"Fail
ed to load NIF library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н
├н├╗├й ├м├о├д├│├л├╝.'"}}},[{'Elixir.Markdown',init,0,[{file,"u:/ex_doc/lib/markd
own.ex"},{line,6}]},{code_server,'-handle_on_load/4-fun-0-'...
=ERROR REPORT==== 1-Jul-2013::17:37:33 ===
The on_load function for module Elixir.Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF
library u:/ex_doc/share/markdown: '├Н├е ├н├а├й├д├е├н ├│├к├а├з├а├н├н├╗├й ├м├о├д├
│├л├╝.'"}}},
[{'Elixir.Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-f
un-0-',
1,
[{...}|...]}]}
F.....
Failures:
test to_html autolink http address (MarkdownTest)
** (UndefinedFunctionError) undefined function: Markdown.to_html/1
stacktrace:
Markdown.to_html("https://github.com/elixir-lang")
test/markown_test.exs:18: MarkdownTest."test to_html autolink http addres
s"/1
test to_html generate the HTML from the markdown (MarkdownTest)
** (UndefinedFunctionError) undefined function: Markdown.to_html/1
stacktrace:
Markdown.to_html("# Test")
test/markown_test.exs:7: MarkdownTest."test to_html generate the HTML fro
m the markdown"/1
test to_html raises an ArgumentError if the value passed is nil (MarkdownTe
st)
** (ExUnit.AssertionError) Expected exception ArgumentError, got UndefinedF
unctionError (undefined function: Markdown.to_html/1)
at test/markown_test.exs:11
test generate_docs accepts relative directories (ExDocTest)
** (UndefinedFunctionError) undefined function: Markdown.to_html/1
stacktrace:
Markdown.to_html("moduledoc\n\n## Example\n CompiledWithDocs.example\n
")
lib/templates/module_template.eex:32: ExDoc.HTMLFormatter.module_template
/6
lib/ex_doc.ex:81: ExDoc.generate_module_page/4
lib/ex_doc.ex:75: ExDoc.generate_list/5
u:/elixir/lib/elixir/lib/enum.ex:293: Enum."-each/2-lists^foreach/1-0-"/2
u:/elixir/lib/elixir/lib/enum.ex:293: Enum.each/2
test/exdoc_test.exs:29: ExDocTest."test generate_docs accepts relative di
rectories"/1
u:/elixir/lib/elixir/lib/enum.ex:293: Enum.each/2
test/exdoc_test.exs:45: ExDocTest."test generate_docs generates all listi
ng files"/1
u:/elixir/lib/elixir/lib/enum.ex:293: Enum.each/2
test/exdoc_test.exs:35: ExDocTest."test generate_docs generates in specif
ied output directory"/1
u:/elixir/lib/elixir/lib/enum.ex:293: Enum.each/2
test/exdoc_test.exs:23: ExDocTest."test generate_docs generates the html
file with the documentation"/1
u:/elixir/lib/elixir/lib/enum.ex:293: Enum.each/2
test/exdoc_test.exs:65: ExDocTest."test generate_docs generates the sourc
e link with the specified url"/1
test module_page outputs behavior and callbacks (ExDoc.HTMLFormatterTest)
** (UndefinedFunctionError) undefined function: Markdown.to_html/1
stacktrace:
Markdown.to_html("This is a sample callback.\n")
lib/templates/detail_template.eex:5: ExDoc.HTMLFormatter.detail_template/
1
lib/templates/module_template.eex:102: ExDoc.HTMLFormatter."-module_templ
ate/6-lc$^7/1-7-"/1
lib/templates/module_template.eex:102: ExDoc.HTMLFormatter.module_templat
e/6
test/exdoc/html_formatter_test.exs:62: ExDoc.HTMLFormatterTest."test modu
le_page outputs behavior and callbacks"/1
test module_page outputs summaries (ExDoc.HTMLFormatterTest)
** (UndefinedFunctionError) undefined function: Markdown.to_html/1
stacktrace:
Markdown.to_html("moduledoc\n\n## Example\n CompiledWithDocs.example\n
")
lib/templates/module_template.eex:32: ExDoc.HTMLFormatter.module_template
/6
test/exdoc/html_formatter_test.exs:55: ExDoc.HTMLFormatterTest."test modu
le_page outputs summaries"/1
test module_page outputs the functions and docstrings (ExDoc.HTMLFormatter
Test)
** (UndefinedFunctionError) undefined function: Markdown.to_html/1
stacktrace:
Markdown.to_html("moduledoc\n\n## Example\n CompiledWithDocs.example\n
")
lib/templates/module_template.eex:32: ExDoc.HTMLFormatter.module_template
/6
test/exdoc/html_formatter_test.exs:41: ExDoc.HTMLFormatterTest."test modu
le_page outputs the functions and docstrings"/1
Finished in 13.8 seconds (4.3s on load, 9.5s on tests)
43 tests, 11 failures
tovmasyan@input255 ~/ex_doc
$
The current implementation of ExDoc contains a series of issues, I would like to fix in the long term. The most prominent consequence of those issues is the difficulty in testing, either because the APIs are not well exposed or because the different modules are too coupled. The main issues are:
ExDoc as the main driver for logic. Initially we have thought about having ExDoc driving the main logic by simply calling functions on the formatter. This approach limits greatly what the compiler can achieve. My proposal is to change ExDoc to simply call: formatter.run(data, config)
and let the formatter do whatever it pleases. This will make it easy to unit test ExDoc
, because we can simply create a dummy formatter that returns the given data and config. Data is meant to be the information returned from the retriever and config is the current ExDoc config record.
The ExDoc.Retriever module was created with ExDoc in mind. Its only API is get_docs
which expects a bunch of files, which, once again, make them hard to test. Instead I would like the retriever to work against a list of modules names, which is possible because aliases in Elixir can exist without the underlying module existing, like ThisIsUnknown
. Again, the direct benefit is that testability becomes, because we can simply pass a module for testing, instead of having to generate actual beam files. My proposed API for this module would be:
ExDoc.Retriever.docs_from_dir(dir, config)
ExDoc.Retriever.docs_from_files(files, config)
ExDoc.Retriever.docs_from_modules(files, config)
docs_from_dir
should simply do a wildcard on the given directory for ebin fles, which are then passed to files which then calls modules. I would also like to change the ExDoc.Retriever
to return the full list of docs, without nesting or segregation by protocols or records. Nesting and segregation should be done by the underlying formatter on whatever way it pleases. We could provide helpers for such functionality either as extra functions in ExDoc.Retriever
.
Finally, since those changes will likely move more logic into the formatter, I would like to split the current formatter in two modules. One that will do the required assembling and another one only with the templates. Today, both templates and assembling are in the same module, which cases confusion. For example, it would be wise to still keep the parts that write to disk decoupled from the template, so we can test the template without a need to read and write to disk.
As the main goal here is provide a well documented and tested project, it is important to document and update tests as we go, getting rid of the old, coupled tests in favor of new ones.
For example, List.Chars should be visible at:
List
> Chars
I think it would be a good idea to make publishing docs as quickly as possible. With github project pages we can publish static html quickly.
I would like to create a mix task named docs.publish or docs.gh-pages that would
I'm looking for a nod of approval before I write the code and create a PR.
I think adding it to ex_doc directly instead of another package would make this easy for folks to get in the habit of publishing docs.
We need to upgrade to Elixir v0.14.0-dev:
module.__info__(:docs)
. Instead Code.get_docs(module, :all)
should be used__struct__
function. If such function is defined and its documentation is not set to false, we are going to tag it as struct. We will also detect exceptions similarly if the struct has an exception fieldModules | Records | Protocols
pages in favor of a single listing. We will still keep the tags so they are shown along side the module name in the module page, but we will no longer break the listingIt would be super nice to have syntax highlighting for all of the code examples in the documentation. I'm guessing this might be a decent bit of work if we can't depend on something like pygments.org.
We should detect if a module is a defrecord and use a special notation for it.
At the end of each method, we can add a link "view source" that points to a given URL. This URL is optional, that said, we should support projects where view source will be enabled or not.
Attempting to do a mix compile, and get this:
david@ubuntu:~/ex_doc$ mix compile
git submodule update --init
Submodule 'sundown' () registered for path 'sundown'
From git://github.com/vmg/sundown
* [new branch] gh-pages -> origin/gh-pages
* [new branch] master -> origin/master
Submodule path 'sundown': checked out '975df6267cbc798ecfcb6948364cd978dc2bf36f'
cd sundown && make
make[1]: Entering directory `/home/david/ex_doc/sundown'
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o src/markdown.o src/markdown.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o src/stack.o src/stack.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o src/buffer.o src/buffer.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o src/autolink.o src/autolink.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o html/html.o html/html.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o html/html_smartypants.o html/html_smartypants.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o html/houdini_html_e.o html/houdini_html_e.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o html/houdini_href_e.o html/houdini_href_e.c
gcc -g -O3 -Wall -Werror -shared -Wl src/markdown.o src/stack.o src/buffer.o src/autolink.o html/html.o html/html_smartypants.o html/houdini_html_e.o html/houdini_href_e.o -o libsundown.so.1
gcc: error: unrecognized command line option ‘-Wl’
make[1]: *** [libsundown.so.1] Error 1
make[1]: Leaving directory `/home/david/ex_doc/sundown'
make: *** [sundown/libsundown.so] Error 2
gcc -version gives me this:
gcc (Ubuntu/Linaro 4.7.2-2ubuntu1) 4.7.2
We should inspect the documentation source and provide autolinking. For example, if we mention a function as function/2
, we should automatically add a documentation link for it. The same for external functions as External.function/2
.
Kernel.++/2
doesn't appear to auto-link in the docs. Probably need to update the regex for discovering functions. Should also validate other special forms.
$ mix -v
Elixir 0.10.4-dev
/projects/ex_doc$ mix compile
** (ArgumentError) argument error
:io.put_chars(#PID<0.24.0>, :unicode, [<<109, 97, 107, 101, 58, 32, 34, 112, 114, 105, 118, 47, 109, 97, 114, 107, 100, 111, 119, 110, 46, 115, 111, 34, 32, 228, 114, 32, 102, 228, 114, 115, 107, 46, 10>>, 10])
/projects/elixir/lib/mix/lib/mix/tasks/compile.ex:78: Mix.Tasks.Compile."-run/1-fun-2-"/2
/projects/elixir/lib/elixir/lib/enum.ex:675: Enum."-map/2-lc$^0/1-0-"/2
/projects/elixir/lib/mix/lib/mix/tasks/compile.ex:77: Mix.Tasks.Compile.run/1
/projects/elixir/lib/mix/lib/mix/cli.ex:61: Mix.CLI.run_task/2
We need to have source links in the stable docs point to a frozen commit/tag. Currently, this is what the source link of Enum.map
points to in both master and stable docs -- https://github.com/elixir-lang/elixir/blob/master/lib/elixir/lib/enum.ex#L554
Discuss!
We need to discuss more about this before going forward.
The source links here: http://elixir-lang.org/docs/ecto/ points to the current page instead of the github repo. Seems to be because the href attribute is empty.
Check any function defined by protocols, their signature contains xA, xB and so forth.
Go to http://elixir-lang.org/docs/ and type size in the search box. You'll get one entry for the Dict protocol's function and one docless entry for each implementation. Docs won't be written for implementations (in general) so we should probably make @doc false a default for them.
Original report here: elixir-lang/elixir#293
We should be able to generate autolinks for types in modules of the same project. /cc @pminten
Here: http://elixir-lang.org/docs/master/Version.html we link to the types Version.Schema.t
and Version.Requirement.t
. The types are not documented which is creating 404 links.
We should make sure we are not creating 404 links and we could warn that we are referencing a type that is not documented.
:)
Today, functions can have default values, as in:
def foo(bar // 0)
But Elixir does not leak this information. This means we can't know if a given function was generated from a default clause and we need to fix that first in Elixir and then port the features here.
Hello,
Tried to build docs with mix docs
but getting error:
** (UndefinedFunctionError) undefined function: :supervisor.__info__/1
:supervisor.__info__(:attributes)
deps/ex_doc/lib/ex_doc/retriever.ex:208: ExDoc.Retriever.callbacks_of/1
deps/ex_doc/lib/ex_doc/retriever.ex:203: ExDoc.Retriever."-callback_implementations/1-fun-1-"/1
/home/shk/work/elixir/lib/elixir/lib/enum.ex:675: Enum."-map/2-lc$^0/1-0-"/2
deps/ex_doc/lib/ex_doc/retriever.ex:203: ExDoc.Retriever.callback_implementations/1
deps/ex_doc/lib/ex_doc/retriever.ex:88: ExDoc.Retriever.generate_node/3
/home/shk/work/elixir/lib/elixir/lib/enum.ex:675: Enum."-map/2-lc$^0/1-0-"/2
/home/shk/work/elixir/lib/elixir/lib/enum.ex:675: Enum."-map/2-lc$^0/1-0-"/2
Any ideas?
Placing the ExDoc dependency in the mix.exs
file at the root of an umbrella project and running mix docs
does not generate documentation for each application found within your apps
directory.
It would be awesome to be able to manipulate documentation at the umbrella level!
We'd like to be able to add user's guides to our documentation, like Erlang has.
The current plan is to allow passing a list of markdown files to ex_doc which will be used as the user's guide. Directories can be passed as well, those are expanded to the files in them (alphabetically).
This may be related to #31
I had a report in the book errata page:
Fetching and building the ex_doc dependency leads to errors on ubuntu 13.04.
Fix is to edit deps/ex_doc/sundown/Makefile and remove the "-Wl" on line 44, then run mix deps.compile to fix up.--Ant Skelton
We should detect if a module is a defrecord and use a special notation for it.
We should detect if a module is a defprotocol or defimpl and use a special notation for it.
For example, EEx.AssignsEngine
has no children but it still has the "drop down icon": http://elixir-lang.org/docs/master/
How do you compile ex_doc with Elixir-0.13.0 ? The latest release on Elixir is 0.13.0 but then the Elixir asked for in ex_doc's mix.exs is 0.13.1-dev ?
Hey, I'm trying to create some docs here.
Seems like ex_docs are looking for a file that can't be found. Did we loose it somewhere along the line, or should I have it from somewhere else?
$ mix docs
=ERROR REPORT==== 31-May-2013::23:14:38 ===
Error in process <0.79.0> with exit value: {{badmatch,{error,{load_failed,"Failed to load NIF library: '/home/kitofr/code/elixir/issues/deps/ex_doc/share/markdown.so: cannot open shared object file: No such file or directory'"}}},[{'Elixir.Markdown'...
Right now, e.g. GenServer.Behaviour
shows up with its full module name in the module list. This is of course because there's no GenServer
parent module, but the behavior is rather confusing to someone not in the know; it gives the impression that other modules don't have submodules (e.g. Kernel.SpecialForms
isn't in the list). With the current behavior, submodules also aren't very discoverable in general.
I see two ways to deal with this:
GenServer
would either not be clickable or would just show a page saying "nothing here". This doesn't really solve the discoverability issue, though.Thoughts? Any other ideas?
A weird thing happened. I clearly remember changing the README here because I was able to generate docs for a project that way. And it corresponds with the usage docstring.
Today I was getting this error on two different projects – https://github.com/elixir-lang/ex_doc/blob/master/lib/ex_doc/retriever.ex#L53-L54. If you examine the code path leading to this line, it doesn't add the directory where the beams are to the load path. So the user still needs to run ex_doc
with elixir -pa path/to/ebin ex_doc <project name> <version> path/to/ebin
.
I thought ex_doc
would append the path automatically. Users don't have to know it relies on Code.ensure_loaded?
.
We should be able to generate autolinks to external functions in modules that belong to the same project.
I build according to "Using ExDoc via command line" in README and I get the following error message.
/Users/yuki_ito/dev% git clone [email protected]:elixir-lang/ex_doc.git
Cloning into 'ex_doc'...
remote: Counting objects: 1293, done.
remote: Compressing objects: 100% (738/738), done.
remote: Total 1293 (delta 520), reused 1274 (delta 507)
Receiving objects: 100% (1293/1293), 388.55 KiB | 186 KiB/s, done.
Resolving deltas: 100% (520/520), done.
/Users/yuki_ito/dev% cd ex_doc/
/Users/yuki_ito/dev/ex_doc% mix compile
git submodule update --init
Submodule 'sundown' (git://github.com/vmg/sundown.git) registered for path 'sundown'
Cloning into 'sundown'...
Submodule path 'sundown': checked out '975df6267cbc798ecfcb6948364cd978dc2bf36f'
cd sundown && make
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o src/markdown.o src/markdown.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o src/stack.o src/stack.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o src/buffer.o src/buffer.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o src/autolink.o src/autolink.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o html/html.o html/html.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o html/html_smartypants.o html/html_smartypants.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o html/houdini_html_e.o html/houdini_html_e.c
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o html/houdini_href_e.o html/houdini_href_e.c
gcc -g -O3 -Wall -Werror -shared -Wl src/markdown.o src/stack.o src/buffer.o src/autolink.o html/html.o html/html_smartypants.o html/houdini_html_e.o html/houdini_href_e.o -o libsundown.so.1
ln -f -s libsundown.so.1 libsundown.so
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o examples/sundown.o examples/sundown.c
gcc -g -O3 -Wall -Werror examples/sundown.o src/markdown.o src/stack.o src/buffer.o src/autolink.o html/html.o html/html_smartypants.o html/houdini_html_e.o html/houdini_href_e.o -o sundown
gcc -c -g -O3 -fPIC -Wall -Werror -Wsign-compare -Isrc -Ihtml -c -o examples/smartypants.o examples/smartypants.c
gcc -g -O3 -Wall -Werror examples/smartypants.o src/markdown.o src/stack.o src/buffer.o src/autolink.o html/html.o html/html_smartypants.o html/houdini_html_e.o html/houdini_href_e.o -o smartypants
gcc -g -O3 -fPIC -Isundown/src -Isundown/html -I/usr/local/lib/erlang/erts-5.10.1/include -shared -dynamiclib -undefined dynamic_lookup -o share/markdown.so sundown/html/html.o sundown/html/html_smartypants.o sundown/html/houdini_html_e.o sundown/html/houdini_href_e.o sundown/src/buffer.o sundown/src/autolink.o sundown/src/stack.o sundown/src/markdown.o src/markdown_nif.c src/render_ansi.c
Compiled lib/ex_doc/cli.ex
=ERROR REPORT==== 15-May-2013::19:36:48 ===
Error in process <0.68.0> with exit value: {{badmatch,{error,{load_failed,"Failed to load NIF library: 'dlopen(/Users/yuki_ito/dev/ex_doc/share/markdown.so, 2): no suitable image found. Did find:\n /Users/yuki_ito/dev/ex_doc/share/markdown.so:...
=ERROR REPORT==== 15-May-2013::19:36:48 ===
The on_load function for module Elixir-Markdown returned {{badmatch,
{error,
{load_failed,
"Failed to load NIF library: 'dlopen(/Users/yuki_ito/dev/ex_doc/share/markdown.so, 2): no suitable image found. Did find:\n\t/Users/yuki_ito/dev/ex_doc/share/markdown.so: mach-o, but wrong architecture'"}}},
[{'Elixir-Markdown',
init,0,
[{file,...},
{...}]},
{code_server,
'-handle_on_load/4-fun-0-',
1,
[{...}|...]}]}
Compiled lib/markdown.ex
Compiled lib/mix_docs.ex
Compiled lib/ex_doc.ex
Compiled lib/ex_doc/html_formatter.ex
Compiled lib/ex_doc/retriever.ex
Generated ex_doc.app
I use Max OS X 10.7.4, Erlang R16B and Elixir master branch.
iex info
/Users/yuki_ito/% iex
Erlang R16B (erts-5.10.1) [source] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false]
Interactive Elixir (0.8.3.dev) - press Ctrl+C to exit (type h() ENTER for help)
gcc info
/Users/yuki_ito% gcc --version
i686-apple-darwin11-llvm-gcc-4.2 (GCC) 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2336.11.00)
Copyright (C) 2007 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
In elixir-lang/elixir@d33463d, @josevalim removed the signature info from the Behaviour
docs. This is generating a match error in ExDoc.Retriever.get_callback/4
, where we use the signature information in the ExDoc.FunctionNode
. Does this information live some other place in the beam file? Or is there a better way to capture it for the docs?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.