Re: [PU Branch] Documentation with Sphinx

[Jiri Kuncar]

Hello,
Sphinx documentation project in Invenio was just proof-of-concept if we can 
replace 
our custom webdoc. If you have a proposal how to organize user/admin/developers 
documentation, please share your ideas.

Thanks.

Best regards,
-- 
Jiří Kunčar

On 27. 3. 2014, at 10:56, Graham R. Armstrong 
 wrote:

> That's what I'd like to see, Matcher has it's API available (once merged) 
> which is what should be available to other parts of Invenio. API-per-module 
> would be the sensible way to organise it, then underneath document the 
> lower-level code docs.
> 
> Thanks for the responses.
> Graham
> 
> On 27/03/14 10:38, Jan Åge Lavik wrote:
>> Right now the docs seems to just be listed all in one page (see for example 
>> api.rst) without a detailed index or toc. This happens when we add the 
>> "automodule" syntax in the api.rst or modules.rst files. This will get messy 
>> as soon as all the other modules are added here. Will module level 
>> documentation be automatically collected without being listed in these 
>> files? If so, where would we find it?
>> 
>> One of the things that would be nice to have is a page per module, for 
>> example with everything you need to know about "tags" module. This page may 
>> then even have another hierarchy of docs below detailing high to low level 
>> APIs, admin/CLI manuals etc.
>> 
>> Overall, though, this new documentation scheme looks promising and we are 
>> ready to help shape it further :-)
>> 
>> Cheers,
>> Jan
>> 
>> 
>> On Thu, Mar 27, 2014 at 9:25 AM, Tibor Simko  wrote:
>> On Wed, 26 Mar 2014, Graham R. Armstrong wrote:
>> > Having gotten the API for Matcher in place, I'm wondering how we're
>> > planning to collect together documentation for PU.
>> 
>> For APIs, the rough plan was to document methods inside restful files
>> using rst docstrings, and then the overall machinery would collect and
>> build the complete API docs out of these per-module inline docs.
>> 
>> Best regards
>> --
>> Tibor Simko
>> 
> 



smime.p7s
Description: S/MIME cryptographic signature

Re: [PU Branch] Documentation with Sphinx

[Graham R. Armstrong]

That's what I'd like to see, Matcher has it's API available (once 
merged) which is what should be available to other parts of Invenio. 
API-per-module would be the sensible way to organise it, then underneath 
document the lower-level code docs.


Thanks for the responses.
Graham

On 27/03/14 10:38, Jan Åge Lavik wrote:
Right now the docs seems to just be listed all in one page (see for 
example api.rst) without a detailed index or toc. This happens when we 
add the "automodule" syntax in the api.rst or modules.rst files. This 
will get messy as soon as all the other modules are added here. Will 
module level documentation be automatically collected without being 
listed in these files? If so, where would we find it?


One of the things that would be nice to have is a page per module, for 
example with everything you need to know about "tags" module. This 
page may then even have another hierarchy of docs below detailing high 
to low level APIs, admin/CLI manuals etc.


Overall, though, this new documentation scheme looks promising and we 
are ready to help shape it further :-)


Cheers,
Jan


On Thu, Mar 27, 2014 at 9:25 AM, Tibor Simko > wrote:


On Wed, 26 Mar 2014, Graham R. Armstrong wrote:
> Having gotten the API for Matcher in place, I'm wondering how we're
> planning to collect together documentation for PU.

For APIs, the rough plan was to document methods inside restful files
using rst docstrings, and then the overall machinery would collect and
build the complete API docs out of these per-module inline docs.

Best regards
--
Tibor Simko

Re: [PU Branch] Documentation with Sphinx

[Jan Åge Lavik]

(Sorry for double posting - sent from wrong e-mail)

Right now the docs seems to just be listed all in one page (see for example
api.rst) without a detailed index or toc. This happens when we add the
"automodule" syntax in the api.rst or modules.rst files. This will get
messy as soon as all the other modules are added here. Will module level
documentation be automatically collected without being listed in these
files? If so, where would we find it?

One of the things that would be nice to have is a page per module, for
example with everything you need to know about "tags" module. This page may
then even have another hierarchy of docs below detailing high to low level
APIs, admin/CLI manuals etc.

Overall, though, this new documentation scheme looks promising and we are
ready to help shape it further :-)

Cheers,
Jan

Cheers,
Jan

---
Jan Age Lavik
System Developer
INSPIRE-HEP 

Github: @jalavik 
Work phone: +41 22 76 78682


On Thu, Mar 27, 2014 at 10:38 AM, Jan Åge Lavik  wrote:

> Right now the docs seems to just be listed all in one page (see for
> example api.rst) without a detailed index or toc. This happens when we add
> the "automodule" syntax in the api.rst or modules.rst files. This will get
> messy as soon as all the other modules are added here. Will module level
> documentation be automatically collected without being listed in these
> files? If so, where would we find it?
>
> One of the things that would be nice to have is a page per module, for
> example with everything you need to know about "tags" module. This page may
> then even have another hierarchy of docs below detailing high to low level
> APIs, admin/CLI manuals etc.
>
> Overall, though, this new documentation scheme looks promising and we are
> ready to help shape it further :-)
>
> Cheers,
> Jan
>
>
> On Thu, Mar 27, 2014 at 9:25 AM, Tibor Simko  wrote:
>
>> On Wed, 26 Mar 2014, Graham R. Armstrong wrote:
>> > Having gotten the API for Matcher in place, I'm wondering how we're
>> > planning to collect together documentation for PU.
>>
>> For APIs, the rough plan was to document methods inside restful files
>> using rst docstrings, and then the overall machinery would collect and
>> build the complete API docs out of these per-module inline docs.
>>
>> Best regards
>> --
>> Tibor Simko
>>
>
>

Re: [PU Branch] Documentation with Sphinx

[Tibor Simko]

On Wed, 26 Mar 2014, Graham R. Armstrong wrote:
> Having gotten the API for Matcher in place, I'm wondering how we're
> planning to collect together documentation for PU.

For APIs, the rough plan was to document methods inside restful files
using rst docstrings, and then the overall machinery would collect and
build the complete API docs out of these per-module inline docs.

Best regards
-- 
Tibor Simko