search

jelly-beam / rebar3_ex_doc

rebar3 plugin for generating docs with ex_doc
Apache License 2.0
43 stars 13 forks source link

Handling of edoc files #19

Closed kianmeng closed 2 years ago

kianmeng commented 2 years ago

Is there any way to include edoc files and generate doc through rebar3_ex_doc? For example, edoc files within this repo, https://github.com/massemanet/redbug/tree/master/doc.

paulo-ferraz-oliveira commented 2 years ago

@kianmeng, when I first ran rebar3_ex_doc it seemed to have cleared doc (I was also using overview.edoc and had a .gitignore in the folder), so I imagined with was explicitly made so, but am also curious regarding the reply to your question, since it would be neat to at least have a way to smoothly transition (I ended up taking the edoc files and converting them to Markdown, outside of doc).

starbelly commented 2 years ago

@kianmeng If I understand your question correctly, you're wanting to know if we can convert edoc output to ex_doc style and such? If so, there is currently no way to do this, the docs generated by ex_doc come from BEAM chunks vs edoc output.

@paulo-ferraz-oliveira Anything in doc shouldn't be blown away, is that what happened to you?

kianmeng commented 2 years ago

@starbelly Thanks for the answer. It seemed no other ways except what @paulo-ferraz-oliveira suggested, manually convert the edoc file to md file. Since it involved some manual tweaking, and I only have basic knowledge of Erlang and EDoc, I'll ask the Erlang library owner whether they want to migrate to ex_doc first before submitting a PR.

By the way, do you guys know which Erlang libraries to explore first for edoc to ex_doc migration, so we've a standard documentation layout for both Elixir and Erlang libraries?

Or do we wait until the Erlang support for ex_doc, https://github.com/elixir-lang/ex_doc/issues/1333 have completed, or EEP 059, https://www.erlang.org/eeps/eep-0059, have been accepted and implemented?

paulo-ferraz-oliveira commented 2 years ago

@paulo-ferraz-oliveira Anything in doc shouldn't be blown away, is that what happened to you?

Yeah, I believe the whole folder was just deleted. I had, in the past, overview.edoc there, so am pretty certain my procedures wouldn't do that.

...

I just tried it again, and the files were removed. It's not a big deal, for me, since I do not want to mix edoc and ex_doc but it might be for some (especially if you run this without eg. having staged your files).

starbelly commented 2 years ago

Yeah, it shouldn't be so destructive. I'll have to track down where that's happening. It's been a minute.

kianmeng commented 2 years ago

Close as the question have been answered, https://github.com/starbelly/rebar3_ex_doc/issues/19#issuecomment-1100908017.

starbelly commented 2 years ago

@paulo-ferraz-oliveira This happens here https://github.com/elixir-lang/ex_doc/blob/935f2dac019d0bdcb470e68fc8b077e4e27bfe15/lib/ex_doc/formatter/html.ex#L149

If ex_doc has already been run once, your edoc output won't be purged, otherwise it will. That behaviour would have to be changed in ex_doc of course, thus I will close the issue here.

paulo-ferraz-oliveira commented 2 years ago

Sure. Not a big problem to me, though, as stated before. I had rebar3 edoc stuff, not rebar3_ex_doc stuff 👍