search

quasiquoting / lodox

:truck: MOVED to lfe-rebar3/lodox :truck:
https://github.com/lfe-rebar3/lodox
MIT License
5 stars 4 forks source link

Option for destination directory? #41

Closed oubiwann closed 8 years ago

oubiwann commented 8 years ago

Is there a way to override the default destination directory?

If not, may I suggest updating the plugin to support something like rebar3 lfe lodox --output=some/path?

Here's my use case for several LFE projects:

Once I can override the lodox output directory, I'll be able to start using for these projects :-)

oubiwann commented 8 years ago

Well, I said --output flag, but I'd be just as happy with a settable rebar.config or lfe.config option.

yurrriq commented 8 years ago

This will be included in the configuration revamp. For now it's called output-path.

Thanks for these questions, suggestions and bug reports. Keep them coming!

yurrriq commented 8 years ago

Should lodox output be versioned too? For now it's not and output-path is the home for the latest output.

I guess with that you can change output-path as you change your vsn, but that seems lame and overly manual.

We do have access to vsn at runtime so it'd be possible to write to, e.g. output-path/{{vsn}} dynamically.

Thoughts?

oubiwann commented 8 years ago

I was kinda of bummed when Slate didn't offer versioned docs. But after thinking about it, I realized (duh) that a bit of a manual process, as you say, helped me get around that (which I codified in make targets).

I've now gotten used to that for Slate, so I'd just assumed I'd do that with lodox. If you are interested in adding support for versioned docs, I'd probably be +1 on that :-) Though I'd almost certainly want flags for that capability so that my Makefile could generate both a "current" and a "versioned" set of docs (or you could provide a symlink by default?).

Also, I'd probably stay away from module-level vsn, since that is sometimes used independently of the project-level version. Hrm ... though it would make a good configurable option (off by default), e.g., use-vsn? for those that wanted to. There's an lutil function that will get the version number from the .app.src or .app file for a project (I think it also works for OTP releases, but I'd want to double-check that). That might be a good way to go.

Thinking about this more ... a workflow might go like this

  1. version my project
  2. generate docs to a configured dir (e.g., docs/build/api) with a symlink created (docs/build/api/current) sibling to the versioned docs directory just created (docs/build/api/0.1.0)
  3. add versioned docs and symlink to repo
  4. bump version number of project
  5. regen docs (docs/build/api/0.2.0)
  6. add new dir to repo, update changes to symlink

That probably outlines my approach. If that's what was done, then I'll I'd ever need to do is simply run rebar3 lfe lodox without having to add any flags. I'd only need the flags if lodox didn't generate a symlink...

You'd probably want to provide a meta-refresh index page in BUILD_DIR that redirects to current. In which case, configuration would need to have a base-url option, I think ... You'd probably also want to generate a list of links for previous versions of the docs, so they could be added to a drop-down in the header or something. Maybe as simple as finding all top-level dirs in BUILD_DIR?

If all this is too much for right now, I'm totally cool adapting the Makefile approach I use for Slate. In which case I'd just use lodox configuration and system tools to get what I needed for versioned docs. It would be a shame for a nice-to-have pulling you away from the urgent feature dev you've identified!

yurrriq commented 8 years ago

Ah, by vsn I meant in the application resource file. Lodox gets that via rebar3. It could be cool to parse module vsn too.

These are all great ideas. I guess I'll want to break them up into smaller tasks and try to chip away at them.

yurrriq commented 8 years ago

Re: module-level vsn. Right now I'm parsing out the behaviour and it could be cool, if nothing else, to show the module vsn there. The behaviour rendering could use some work too..

yurrriq commented 8 years ago

You can do this now in develop:

{lodox,
 [{apps,
   [{yourproject,
     [{'source-uri',
       "https://github.com/username/yourproject/blob/{version}/{filepath}#L{line}"},
      {'output-path', "relative/path/to/output"}]}]}]}.

where output-path is relative to app-dir or cwd.

oubiwann commented 8 years ago

I tried doing this in a new project: and ran across a few speedbumps.

First, I misinterpreted the example above -- I didn't realize that the lodox under apps was for a given project, and not for lodox itself. As such, for future users who come across this ticket, I could have them look at this instead:

{lodox,
 [{apps,
   [{yourproject,
     [{'source-uri',
       "https://github.com/username/yourproject/blob/{version}/{filepath}#L{line}"},
      {'output-path', "relative/path/to/output"}]}]}]}.

Second, I didn't realize that if the parent directory of the source dir didn't exist, lodox would silently fail to create the docs :-( (no docs, but no error message either). I've added a dependency make target to my project to ensure that the docs parent dir exists before running rebar3 lfe lodox.

With those two out of the way, though, this feature is looking great!

Thanks!

yurrriq commented 8 years ago

Thanks for clarifying the example. I've updated mine above too to avoid confusion. I've been dogfooding Lodox, so that example makes sense to me and likely no one else.

Actually, I'm not sure I understand what you mean when you say "if the parent directory of the source dir didn't exist." Wait, after reading about your make hacks I think I get it. Lodox currently only tries to create the last element of the path, e.g. output in the example, but does nothing to relative, relative/path or relative/path/to.

I'm using file:make_dir/1 and the docstring mentions:

Missing parent directories are not created.

I'll figure out a solution and close #53.

Thanks again for your insightful feedback.