Documentation created automatically

[abelsiqueira]

This uses some pieces from the man page and the function arguments to create a simple documentation for the core interface.

[dpo]

If we're going to keep generating this documentation automatically, I'm wondering if we should store it in a separate file. I believe there's a way to attach a docstring to a function defined elsewhere.

I'm not insisting, but it looks like most of the file is taken up by the docstrings now, which makes it harder to navigate. What do you think?

[abelsiqueira]

I tried to do that when using the man pages using something from the documentation but it didn't work. I will have time tomorrow and will test it again.

[abelsiqueira]

I could only use Docile's external file when also using Lexicon, and I could only make it work on 0.4.
The documentation isn't clear enough on this point, maybe because of the migration of @doc to 0.4.

[dpo]

What I had in mind is something like this (from the link you gave):

"""
Method ``f(::Any)``.
"""
f(x) = x

"""
Function ``f`` after definition.
"""
f

The definition of f could appear in one file, and its documentation in another, that is included.

[abelsiqueira]

That worked, but 0.3 has the limitation of not showing in the REPL. Should I add a conditional import Lexicon as mentioned here or wait for 0.4?

[dpo]

Is there a way to require it only for 0.3?

[abelsiqueira]

From what I (didn't) found, it looks like there isn't. Someone asked a similar question on julia-users and the sole answer was negative. I also looked at other packages using Docile and no one did it.

[dpo]

I propose that we not require Docile. We don't need Docile because we're using plain docstrings. Users need Lexicon if they want enhanced documentation. I've started removing Docile from several other of my packages too. What do you think?

[abelsiqueira]

Agreed

[abelsiqueira]

I will destroy some commits in this

[abelsiqueira]

Commits squashed.

[dpo]

Thanks! Will it also be possible to document the specialized interface? If the documentation is stored in a different file, I'm not sure how that works?!

[abelsiqueira]

I believe it's possible too, I'll just create another file with the documentation for the specialized, but it may take a little more time because of all the variations in the interface.
I will make a different PR for that.

[abelsiqueira]

I noticed, running the script again in other computer, that the terminal size was interfering with the manual pages size, regardless of being called inside the script. So I fixed by setting the man width size to a large value. This also removes hyphenation and justification.

[abelsiqueira]

With the last commit, both documentations are created.
I'd rather rebase this after the fix #41, and squash the commits, if you think the output is good enough.

[abelsiqueira]

I was gonna use @doc (@doc foo) foo!, but that doesn't work on 0.3

[dpo]

Let's use plain docstrings everywhere. They work on 0.3 with Docile, and natively on 0.4.

[abelsiqueira]

That's what I did. It's on file src/documentation.jl.

[dpo]

Well actually, maybe I'm wrong about that. I can't get any documentation to show in 0.3. Can you?

[dpo]

Sorry that's not true. I get the docstrings from the Julia interface, but that's all. So defining the docstring elsewhere doesn't work in 0.3 at all, is that right?

[abelsiqueira]

You're right, the documentation is not working with 0.3. In fact I needed Docile and Lexicon and to use @doc """ ... """ ->.
This also works with 0.4 without Docile and Lexicon.

To fix we need to return to if VERSION < ... and add Docile to REQUIRE.
Should we do it, or wait until 0.4 is stable?

[dpo]

Let's wait until 0.4 I think. I like the way you've set things up.

[dpo]

Any chance that you could rebase?

[abelsiqueira]

No problem. Rebased

[dpo]

Thanks! Sorry I was away for a while.