Re: [julia-users] exemplar package for 0.4-style documentation

[Tom Short]

It just hasn't been implemented, yet. Lexicon complains with "type
BasicREPL has no field interface". I'm guessing that a simpler approach
could be used in Lexicon, or it could be implemented in ESS (unfortunately,
no ESS developers really use Julia).

On Wed, Jan 14, 2015 at 4:23 AM, Tamas Papp  wrote:

> On Tue, Jan 13 2015, Tom Short  wrote:
>
> > If you want to try the Sims docs at the REPL, you'll need to checkout
> that
> > package and enter "using Sims, Sims.Lib, Lexicon". Then you can do
> > ?Resistor or ?"Capacitor.
> >
> > Note that the question mark doesn't work in ESS.
>
> Is that an intrinsic limitation of the documentation system/julia/ESS,
> or just something that has not been implemented yet? It would be very
> nice, since other languages (eg R) use ?function too and that works
> nicely in ESS so users are used to it.
>
> Best,
>
> Tamas
>

Re: [julia-users] exemplar package for 0.4-style documentation

[Michael Hatherly]

Just as a note regarding this new syntax for anyone reading:

It’s still being experimented with in Docile/Lexicon, though so far I’ve 
found it much more enjoyable to use.
Package load times aren’t affected nearly as much as with @doc since 
collection and parsing of docstrings
only happens once a user queries the help system.

If anyone has thoughts/ideas they’d like to discuss regarding these kind of 
things then please do head over to
the issues list for either Docile 
 or Lexicon 
.

— Mike
​


On Wednesday, 14 January 2015 00:06:44 UTC+2, tshort wrote:
>
> It's still a bit in flux as the old style is:
>
> @doc """
> my docs...
> """ ->
> myfun(x) = ...
>
> The new style is:
>
> """
> my docs...
> """
> myfun(x) = ...
>
> The new style is in Docile but not in v"0.4-", yet.
>
> The documentation inside Docile is a good start. It uses the new style. 
> Some other notable packages include:
>
> * https://github.com/johnmyleswhite/CSVReaders.jl
>
> * https://tshort.github.io/Sims.jl/
>
> In Sims.jl, I used Mkdocs (mkdocs.org) along with Docile/Lexicon to 
> create that documentation site.
>
>
>
>
>
>
> On Tue, Jan 13, 2015 at 4:59 PM, Douglas Bates  > wrote:
>
>> I'm having difficulty navigating my way around documentation standards 
>> for v"0.4-", and whether the Docile or Lexicon or Markdown packages are 
>> needed.  What would be a good package to study to see how @doc, etc. should 
>> be used?
>>
>
>

Re: [julia-users] exemplar package for 0.4-style documentation

[Tamas Papp]

On Tue, Jan 13 2015, Tom Short  wrote:

> If you want to try the Sims docs at the REPL, you'll need to checkout that
> package and enter "using Sims, Sims.Lib, Lexicon". Then you can do
> ?Resistor or ?"Capacitor.
>
> Note that the question mark doesn't work in ESS.

Is that an intrinsic limitation of the documentation system/julia/ESS,
or just something that has not been implemented yet? It would be very
nice, since other languages (eg R) use ?function too and that works
nicely in ESS so users are used to it.

Best,

Tamas

Re: [julia-users] exemplar package for 0.4-style documentation

[Tom Short]

If you want to try the Sims docs at the REPL, you'll need to checkout that
package and enter "using Sims, Sims.Lib, Lexicon". Then you can do
?Resistor or ?"Capacitor.

Note that the question mark doesn't work in ESS.



On Tue, Jan 13, 2015 at 5:21 PM, Tom Short  wrote:

> The source with doc strings was only recently merged into master. They
> should be there now (but it's not in METADATA, yet). Compare the input and
> output for one of the source files:
>
> * https://github.com/tshort/Sims.jl/blob/master/examples/lib/electrical.jl
>
> * https://tshort.github.io/Sims.jl/examples/lib/#electrical
>
> On Tue, Jan 13, 2015 at 5:14 PM, Douglas Bates  wrote:
>
>> Actually the first place I looked was in your Sims package but I didn't
>> see any documentation strings, of either form, in the Julia sources.  Am I
>> missing something very basic here?
>>
>> On Tuesday, January 13, 2015 at 4:06:44 PM UTC-6, tshort wrote:
>>>
>>> It's still a bit in flux as the old style is:
>>>
>>> @doc """
>>> my docs...
>>> """ ->
>>> myfun(x) = ...
>>>
>>> The new style is:
>>>
>>> """
>>> my docs...
>>> """
>>> myfun(x) = ...
>>>
>>> The new style is in Docile but not in v"0.4-", yet.
>>>
>>> The documentation inside Docile is a good start. It uses the new style.
>>> Some other notable packages include:
>>>
>>> * https://github.com/johnmyleswhite/CSVReaders.jl
>>>
>>> * https://tshort.github.io/Sims.jl/
>>>
>>> In Sims.jl, I used Mkdocs (mkdocs.org) along with Docile/Lexicon to
>>> create that documentation site.
>>>
>>>
>>>
>>>
>>>
>>>
>>> On Tue, Jan 13, 2015 at 4:59 PM, Douglas Bates  wrote:
>>>
 I'm having difficulty navigating my way around documentation standards
 for v"0.4-", and whether the Docile or Lexicon or Markdown packages are
 needed.  What would be a good package to study to see how @doc, etc. should
 be used?

>>>
>>>
>

Re: [julia-users] exemplar package for 0.4-style documentation

[Tom Short]

The source with doc strings was only recently merged into master. They
should be there now (but it's not in METADATA, yet). Compare the input and
output for one of the source files:

* https://github.com/tshort/Sims.jl/blob/master/examples/lib/electrical.jl

* https://tshort.github.io/Sims.jl/examples/lib/#electrical

On Tue, Jan 13, 2015 at 5:14 PM, Douglas Bates  wrote:

> Actually the first place I looked was in your Sims package but I didn't
> see any documentation strings, of either form, in the Julia sources.  Am I
> missing something very basic here?
>
> On Tuesday, January 13, 2015 at 4:06:44 PM UTC-6, tshort wrote:
>>
>> It's still a bit in flux as the old style is:
>>
>> @doc """
>> my docs...
>> """ ->
>> myfun(x) = ...
>>
>> The new style is:
>>
>> """
>> my docs...
>> """
>> myfun(x) = ...
>>
>> The new style is in Docile but not in v"0.4-", yet.
>>
>> The documentation inside Docile is a good start. It uses the new style.
>> Some other notable packages include:
>>
>> * https://github.com/johnmyleswhite/CSVReaders.jl
>>
>> * https://tshort.github.io/Sims.jl/
>>
>> In Sims.jl, I used Mkdocs (mkdocs.org) along with Docile/Lexicon to
>> create that documentation site.
>>
>>
>>
>>
>>
>>
>> On Tue, Jan 13, 2015 at 4:59 PM, Douglas Bates  wrote:
>>
>>> I'm having difficulty navigating my way around documentation standards
>>> for v"0.4-", and whether the Docile or Lexicon or Markdown packages are
>>> needed.  What would be a good package to study to see how @doc, etc. should
>>> be used?
>>>
>>
>>

Re: [julia-users] exemplar package for 0.4-style documentation

[Douglas Bates]

Actually the first place I looked was in your Sims package but I didn't see 
any documentation strings, of either form, in the Julia sources.  Am I 
missing something very basic here?

On Tuesday, January 13, 2015 at 4:06:44 PM UTC-6, tshort wrote:
>
> It's still a bit in flux as the old style is:
>
> @doc """
> my docs...
> """ ->
> myfun(x) = ...
>
> The new style is:
>
> """
> my docs...
> """
> myfun(x) = ...
>
> The new style is in Docile but not in v"0.4-", yet.
>
> The documentation inside Docile is a good start. It uses the new style. 
> Some other notable packages include:
>
> * https://github.com/johnmyleswhite/CSVReaders.jl
>
> * https://tshort.github.io/Sims.jl/
>
> In Sims.jl, I used Mkdocs (mkdocs.org) along with Docile/Lexicon to 
> create that documentation site.
>
>
>
>
>
>
> On Tue, Jan 13, 2015 at 4:59 PM, Douglas Bates  > wrote:
>
>> I'm having difficulty navigating my way around documentation standards 
>> for v"0.4-", and whether the Docile or Lexicon or Markdown packages are 
>> needed.  What would be a good package to study to see how @doc, etc. should 
>> be used?
>>
>
>

Re: [julia-users] exemplar package for 0.4-style documentation

[Tom Short]

It's still a bit in flux as the old style is:

@doc """
my docs...
""" ->
myfun(x) = ...

The new style is:

"""
my docs...
"""
myfun(x) = ...

The new style is in Docile but not in v"0.4-", yet.

The documentation inside Docile is a good start. It uses the new style.
Some other notable packages include:

* https://github.com/johnmyleswhite/CSVReaders.jl

* https://tshort.github.io/Sims.jl/

In Sims.jl, I used Mkdocs (mkdocs.org) along with Docile/Lexicon to create
that documentation site.






On Tue, Jan 13, 2015 at 4:59 PM, Douglas Bates  wrote:

> I'm having difficulty navigating my way around documentation standards for
> v"0.4-", and whether the Docile or Lexicon or Markdown packages are
> needed.  What would be a good package to study to see how @doc, etc. should
> be used?
>

[julia-users] exemplar package for 0.4-style documentation

[Douglas Bates]

I'm having difficulty navigating my way around documentation standards for 
v"0.4-", and whether the Docile or Lexicon or Markdown packages are needed. 
 What would be a good package to study to see how @doc, etc. should be used?