[sphinx-dev] Updates on introspection?

[Larry G. Wapnitsky]

Have any updates been made on analyzing introspection on decorated 
functions?  I have a decorator that appears to be written properly 
(third-party), but am still unable to get the docstrings from the function.

Thanks,
Larry

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To view this discussion on the web visit 
https://groups.google.com/d/msg/sphinx-dev/-/SNZe85UncEIJ.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] autodoc_docstring_signature

[geoff9399]

I'm trying to use' autodoc_docstring_signature = True' in conf.py, but
it has no effect on documenting my classes implemented using the C
API. I can't seem to find an example...

Here is my C doc string.

PyDoc_STRVAR(propertyDoc,
"BoolProperty(name, label, initValue=False)\n"
"\n"
"Construct a boolean property\n"
"\n"
"Keyword arguments:\n"
"name (str) -- the name of the property\n"
"label (str) -- the label of the property, tyically the label
shown in the GUI\n"
"initValue (bool) -- the the initial value (default False)\n"
);

And here is the resulting Sphinx doc, which does not replace the C
constructor with the signature in the first line of the doc string.

class mymodule.BoolProperty
BoolProperty(name, label, initValue=False)

Construct a boolean property

Keyword arguments:
name (str) – the name of the property label (str) – the label of the
property, tyically the label shown in the GUI initValue (bool) – the
the initial value (default False)

Any ideas why it doesn't work?

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] NameError: global name 'key' is not defined

[Andrea]

I am trying to use the natbib module at

https://bitbucket.org/wnielson/sphinx-natbib/

and I get the following message, 
---
Running Sphinx v1.1.3
loading pickled environment... not yet created
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index 

Exception occurred:
  File "/Users/acortis/local/lib/python2.7/site-packages/pybtex/utils.py", 
line 138, in get
return self[self._keys[key.lower()]]
NameError: global name 'key' is not defined
The full traceback has been saved in 
/var/folders/g8/gmdqdykn21x6cwtf3mjwchxwgn/T/sphinx-err-Q_50rt.log, if 
you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error 
message can be provided next time.
Either send bugs to the mailing list at 
,
or report them in the tracker at 
. Thanks!
make: *** [html] Error 1
-

which apparently I need to report to this list (?!?!?!)... please correct 
me if I am wrong thanks. The full log is below

Thanks for your kind assistance

Andrea


acortis-air:test acortis$ vi 
/var/folders/g8/gmdqdykn21x6cwtf3mjwchxwgn/T/sphinx-err-Q_50rt.log

  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 286, in nested_parse
node=node, match_titles=match_titles)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 199, in run
results = StateMachineWS.run(self, input_lines, input_offset)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/statemachine.py",
 
line 239, in run
context, state, transitions)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/statemachine.py",
 
line 460, in check_line
return method(match, context, next_state)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 1222, in bullet
blank_finish=blank_finish)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 323, in nested_list_parse
node=node, match_titles=match_titles)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 199, in run
results = StateMachineWS.run(self, input_lines, input_offset)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/statemachine.py",
 
line 239, in run
context, state, transitions)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/statemachine.py",
 
line 460, in check_line
return method(match, context, next_state)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 2459, in bullet
listitem, blank_finish = self.list_item(match.end())
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 1238, in list_item
node=listitem)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 286, in nested_parse
node=node, match_titles=match_titles)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 199, in run
results = StateMachineWS.run(self, input_lines, input_offset)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/statemachine.py",
 
line 245, in run
result = state.eof(context)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 2649, in eof
self.blank(None, context, None)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 2641, in blank
context, self.state_machine.abs_line_number() - 1)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 422, in paragraph
textnodes, messages = self.inline_text(text, lineno)
  File 
"/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/parsers/rst/states.py",
 
line 431, in inline_text
return self.inliner.parse(te

[sphinx-dev] autodoc_docstring_signature

[Geoffrey Philbrick]

autodoc_docstring_signature does not work for constructors of C classes (the
documentation is clear that it only works for functions and methods). It
works fine for the methods of the class in my examples. Is there any way to
get it to work for the constructors also?

 

Thanks,

 

Geoff

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: How to include bibliography from BibTeX

[Andrea]

Hello everybody,

Sorry for plugging in on an old conversation.

I have been looking now a while on google for a way to solve this problem, 
i.e., how to include bibtex references in sphinx, and I am not still clear 
on how to do it. Could you please advise if there is now a standard way to 
address this need?

Thanks

Andrea

On Monday, May 31, 2010 5:37:52 AM UTC-5, andreash wrote:
>
> Hi, 
>
> thanks for pointing me towards that. From a first glance, bibstuff 
> looks pretty promising. I'll look around docutils-dev to get going ... 
>
> Cheers, 
>
> Andreas. 
>
> On May 31, 8:09 am, Guenter Milde  wrote: 
> > On 2010-05-30, andreash wrote: 
> > > Hi there, 
> > > I am using Zotero (http://www.zotero.org) to manage my bibliography 
> > > database. Is there any way how I can include this bibliography into 
> > > Sphinx? Especially in the HTML output ... I'm not necessarily looking 
> > > for a way to actually use these items (although it would be nice); it 
> > > would rather be sufficient to generate the bibliography, if possible 
> > > with the BibTeX style of my choice ... 
> > > If this is not possible, what would be the best way to implement this? 
> > 
> > The fastest way would be to export from the BibTeX database to HTML (see 
> > below for tools able to do this) and include (or link to) the resulting 
> > file. 
> > 
> > > I'd really be interested in implementing this ... 
> > 
> > There is a TODO item for Docutils regarding citations: 
> > 
> >   Citations: 
> > Collect citations that are referenced ... 
> > 
> > Citations can be: 
> > 
> > a) defined in the document as citation elements 
> > 
> > b) auto-generated from entries in a bibliographic database. 
> > 
> >+ based on bibstuff_? 
> >+ also have a look at 
> > 
> >  * CrossTeX_, a backwards-compatible, improved bibtex 
> >re-implementation in Python (including HTML export). 
> >(development stalled since 2 years) 
> > 
> >  * Pybtex_,a drop-in replacement for BibTeX written in Python. 
> > 
> >* BibTeX styles & (experimental) pythonic style API. 
> >* Database in BibTeX, BibTeXML and YAML formats. 
> >* full Unicode support. 
> >* Write to TeX, HTML and plain text. 
> > 
> > * Automatically insert a "References" heading? 
> > 
> > .. _bibstuff:http://code.google.com/p/bibstuff/ 
> > .. _CrossTeX:http://www.cs.cornell.edu/people/egs/crosstex/ 
> > .. _Pybtex:  http://pybtex.sourceforge.net/ 
> > 
> > Once this is solved in the Docutils core, it will be available for 
> Sphinx 
> > too. 
> > 
> > Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To view this discussion on the web visit 
https://groups.google.com/d/msg/sphinx-dev/-/GilKMjiDKQYJ.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Decorators

[Larry G. Wapnitsky]

Has there been any further documentation on how to deal with decorated 
functions and Sphinx?  I have an entire module filled with 
third-party-decorated functions that can't be auto-documented, hence adding 
a ton of extra work that should not need to be done.

Thanks,
Larry

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To view this discussion on the web visit 
https://groups.google.com/d/msg/sphinx-dev/-/Spv2LbfJ84sJ.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

Re: [sphinx-dev] Annoucing robin, a new Doxygen to Sphinx bridge

[Michael Gielda]

Hi,

My thoughts exactly, Michael, I use your Breathe extension and most of the 
stuff just works... gotta test if the new thing provides more functionality 
but perhaps the authors can point us in the right direction?
I mean Breathe is not ideal but perhaps it would be wiser to fill in the 
blanks than write a new framework from scratch. Still, if it is there, 
perhaps they can benefit mutually from the 'competition'?

Best,
Michael (it's a fairly popular name ;) )

On Sunday, 26 August 2012 00:18:01 UTC+2, mpj wrote:
>
> Hey, 
>
> I wrote Breathe, if you'd be up for providing a short explanation of 
> why you started your project and what advantages you feel your 
> approach has then I'd love to put it in the Breathe readme so that 
> people can see alternatives. 
>
> Cheers, 
> Michael 
>
> On Sat, Jun 16, 2012 at 3:59 AM, Anteru 
> > wrote: 
> > Hi, 
> > 
> > We're happy to announce robin, a new Doxygen/C++ to Sphinx bridge. Robin 
> > provides an easy-to-use, easy-to-hack integration of Doxygen 
> > documentation into Sphinx. Robin is licensed under the BSD and can be 
> > found at Bitbucket: https://bitbucket.org/reima/robin 
> > 
> > Features 
> >  
> > 
> > * Robust extraction of Doxygen XML data via an easy-to-hack parser 
> > * Intermediate data is stored in a database (mongodb) for simple 
> > extraction and processing 
> > * Directive-driven output; each directive provides callbacks and hooks 
> > which allows for deep customization 
> > * Automated generation of driver ReST documents: Similar to automodule; 
> > however, robin generates actual ReST documents which can be inspected 
> > 
> > Prerequisites 
> > = 
> > 
> > Robin expects a running mongodb on the local host. It uses a minimal set 
> > of external libraries: Pymongo, sphinx, progressbar. All of the 
> > dependencies can be easily installed using pip or easy_install. 
> > 
> > Robin has been developed with Python 2.7; we have not tested previous 
> > versions. 
> > 
> > Getting started 
> > === 
> > 
> > * Run Doxygen to generate XML documentation (GENERATE_XML=YES) 
> > * Run extract-doxygen   
> > * Run create-rst  
> >   This generates several directories (classes, groups, etc.) 
> >   Include the groups.rst into your toc 
> > * Add 'robin.sphinx' to the Sphinx extensions 
> > * Build (make html) for TOC update 
> > * Build again (make clean && make html) 
> > 
> > Status 
> > == 
> > 
> > We're using robin internally for a large C++ codebase, and there are a 
> > few minor issues left that we hope to resolve soon (all of them are 
> > tracked on Bitbucket.) After that, we expect that robin will go into 
> > "maintenance" mode focusing on bug fixes only. If someone is interested 
> > in contributing, please get in touch with us. 
> > 
> > Cheers, 
> >   the robin developers 
> > 
> > -- 
> > You received this message because you are subscribed to the Google 
> Groups "sphinx-dev" group. 
> > To post to this group, send email to 
> > sphin...@googlegroups.com. 
>
> > To unsubscribe from this group, send email to 
> sphinx-dev+...@googlegroups.com . 
> > For more options, visit this group at 
> http://groups.google.com/group/sphinx-dev?hl=en. 
> > 
>

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To view this discussion on the web visit 
https://groups.google.com/d/msg/sphinx-dev/-/7Xgdn5bp2hQJ.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

Re: [sphinx-dev] Digest for sphinx-dev@googlegroups.com - 10 Messages in 7 Topics

[Raingo Lee]

On Tue, Aug 28, 2012 at 7:03 AM,   wrote:
>   Today's Topic Summary
>
> Group: http://groups.google.com/group/sphinx-dev/topics
>
> Align figure center and bottom? [2 Updates]
> Figure caption? [1 Update]
> Feature request :nowrap:/:pre-wrap: code-block directive options [2 Updates]
> Underline inline markup? [2 Updates]
> Symbols like "local accents or tildes" [1 Update]
> Problems with get-start in Sphinx. [1 Update]
> Github and Sphinx 2012 [1 Update]
>
>  Align figure center and bottom?
>
> Guenter Milde  Aug 27 01:40PM
>
> On 2012-08-27, Boris Kheyfets wrote:
>
>> /home/boris/pst/wordy/edu/HighestProgramming/00_-_intro.rst:484: ERROR:
>> Error in "image" directive: "bottom" is not a valid value for the "align"
>> option. Valid values for "align" are: "left", "center", "right".
>
> You still use block-level images.
>
>>> which means you need to define your images as inline,
>
> *outside of the table*, via a substitution definition
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions
> e.g.
>
>>> |left-image| |right-image|
>
>>> left caption right caption
>>> === 
>
> (this is a simple table syntax, the | are not table lines but
> mark substitutions).
>
> Günter
>
>
>
> Boris Kheyfets  Aug 28 02:19AM -0700
>
> Doesn't work:
>
> .. |left-image| image:: _static/SuperCompArch.jpg
> :width: 80%
> :alt: Supercomputer archeticture
> :align: bottom
>
> .. |right-image| image:: _static/ClustArch.jpg
> :width: 80%
> :alt: Cluster archeticture
> :align: bottom
>
>  =
> |left-image| |right-image|
>
> left caption right caption
>  =
>
> screenshot 
>
>
> Boris.
>
> On Monday, August 27, 2012 5:40:43 PM UTC+4, Guenter Milde wrote:
>
>
>
>  Figure caption?
>
> Boris Kheyfets  Aug 28 02:08AM -0700
>
> Oh I found it:
>
> See :ref:`link title `.
>
> .. _figure:
>
> .. figure:: _static/UnixFileSystem.jpg
> :width: 50%
> :alt: Unix file system
> :align: center
> :name: test name
>
> Figure caption
>
>
>
> On Monday, August 20, 2012 3:18:52 PM UTC+4, Boris Kheyfets wrote:
>
>
>
>  Feature request :nowrap:/:pre-wrap: code-block directive options
>
> Guenter Milde  Aug 27 01:31PM
>
> On 2012-08-27, Boris Kheyfets wrote:
>
>
>> Do You think I can currently emulate this option -- that is to have pre
>> wrapped at one parts of rst file, and no-wraped in other parts? (while
>> both
>> in code-block)
>
> You can always add a class argument, either via::
>
> .. code:: 
> :class: wrapped
>
> code that wraps in language 
>
> The "class" directive option can also be given to the "include" directive
> (e.g. for included cvs files)::
>
> .. include myfile.cvs
> :code: text
> :class: nowrap
>
> A literal block, can be preceded with a "class" directive::
>
> Now some literal block:
>
> .. class:: wrapped
>
> ::
>
> literal block with the "wrapped" class
>
> See http://docutils.sourceforge.net/docs/ref/rst/directives.html especially
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#class
> for details.
>
> I'd style the default to use the more often required wrapping mode and
> use either "wrap" or "nowrap" class argument (with another rule in the
> custom CSS sheet) for the exceptions.
>
> Günter
>
>
>
> Boris Kheyfets  Aug 28 02:00AM -0700
>
> Doesn't work:
>
> rst file:
>
> .. code:: python
> :class: nowrap
>
> for i in range(5): test test test test test test test test test test
> test test test test
>
> css file:
> I tried:
>
> pre.nowrap {
> white-space: nowrap;
> }
>
> div.nowrap {
> white-space: nowrap;
> }
>
> span.nowrap {
> white-space: nowrap;
> }
>
> none wraps the code.
>
> On Monday, August 27, 2012 5:31:40 PM UTC+4, Guenter Milde wrote:
>
>
>
>  Underline inline markup?
>
> Guenter Milde  Aug 27 01:34PM
>
> On 2012-08-27, Boris Kheyfets wrote:
>
>
>> .. role:: underlined(raw)
>> :format: html
>> :style: text-decoration: underline;
>
> This creates a role based on the raw role, i.e. it expects the content to be
> raw html.
>
> Instead, write
>
> .. role:: underlined
>
> and a CSS rule to style ``span.underlined`` in a custom style sheet.
>
>
> Suggestions/patches improving
>>>
>>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
> to make this more clear are welcome.
>
> Günter
>
>
>
> Boris Kheyfets  Aug 28 01:48AM -0700
>
> It works!
>
> I've added
>
> span.underlined {
> text-decoration: underline;
> }
>
> to default.css
>
> and
>
> .. role:: underlined
>
> :underlined:`test underlined`
>
> to the test.rst and it is underlined!
>
> Thank You!
>
>
> On Monday, August 27, 2012 5:34:51 PM UTC+4, Guenter Milde wrote:
>
>
>
>  Symbols like "local accents or tildes"
>
> e-friend-partner  Aug 27 03:34PM -0700
>
> Hello community!
> Now I have one litle problem :
>
> 1. Install Sphinx 1.1.3 on a Windows-7 Professional and generate the doc
> with
> test sources in Python, but my source codes hav

Re: [sphinx-dev] Annoucing robin, a new Doxygen to Sphinx bridge

[Anteru]

Hi,

we did try Breathe actually; the main problem we had with it was that we
couldn't hack the output easily and that there was no "automodule"
support in it to generate documentation for all files in a project. Our
goal was to make a minimal bridge which is easy to hack, so anything
that is missing can be added easily, and to abstract away from Doxygen
as quickly as possible.

There's still some stuff which can be implemented better in Robin (for
instance, we currently need two passes over the generated .rst files)
but our feeling is that hacking Robin to get it working will be easier
than hacking Breathe. If you take a look at Robin, it's cleanly
separated into one pass which converts from Doxygen to MongoDB, and a
second pass which works on well-structured data. We did actually a split
on the development side, with one author writing each of the parts :)

That's however our personal view, and so far, we do generate the
documentation for a large C++ project with it and we're happy. If
there's anything we can do to make the code more accessible, feel free
to drop us a line.

Cheers

Am 28.08.2012 22:51, schrieb Michael Gielda:
> Hi,
> 
> My thoughts exactly, Michael, I use your Breathe extension and most of
> the stuff just works... gotta test if the new thing provides more
> functionality but perhaps the authors can point us in the right direction?
> I mean Breathe is not ideal but perhaps it would be wiser to fill in the
> blanks than write a new framework from scratch. Still, if it is there,
> perhaps they can benefit mutually from the 'competition'?
> 
> Best,
> Michael (it's a fairly popular name ;) )
> 
> On Sunday, 26 August 2012 00:18:01 UTC+2, mpj wrote:
> 
> Hey,
> 
> I wrote Breathe, if you'd be up for providing a short explanation of
> why you started your project and what advantages you feel your
> approach has then I'd love to put it in the Breathe readme so that
> people can see alternatives.
> 
> Cheers,
> Michael
> 
> On Sat, Jun 16, 2012 at 3:59 AM, Anteru
> > wrote:
> > Hi,
> >
> > We're happy to announce robin, a new Doxygen/C++ to Sphinx bridge.
> Robin
> > provides an easy-to-use, easy-to-hack integration of Doxygen
> > documentation into Sphinx. Robin is licensed under the BSD and can be
> > found at Bitbucket: https://bitbucket.org/reima/robin
> 
> >
> > Features
> > 
> >
> > * Robust extraction of Doxygen XML data via an easy-to-hack parser
> > * Intermediate data is stored in a database (mongodb) for simple
> > extraction and processing
> > * Directive-driven output; each directive provides callbacks and
> hooks
> > which allows for deep customization
> > * Automated generation of driver ReST documents: Similar to
> automodule;
> > however, robin generates actual ReST documents which can be inspected
> >
> > Prerequisites
> > =
> >
> > Robin expects a running mongodb on the local host. It uses a
> minimal set
> > of external libraries: Pymongo, sphinx, progressbar. All of the
> > dependencies can be easily installed using pip or easy_install.
> >
> > Robin has been developed with Python 2.7; we have not tested previous
> > versions.
> >
> > Getting started
> > ===
> >
> > * Run Doxygen to generate XML documentation (GENERATE_XML=YES)
> > * Run extract-doxygen  
> > * Run create-rst 
> >   This generates several directories (classes, groups, etc.)
> >   Include the groups.rst into your toc
> > * Add 'robin.sphinx' to the Sphinx extensions
> > * Build (make html) for TOC update
> > * Build again (make clean && make html)
> >
> > Status
> > ==
> >
> > We're using robin internally for a large C++ codebase, and there
> are a
> > few minor issues left that we hope to resolve soon (all of them are
> > tracked on Bitbucket.) After that, we expect that robin will go into
> > "maintenance" mode focusing on bug fixes only. If someone is
> interested
> > in contributing, please get in touch with us.
> >
> > Cheers,
> >   the robin developers
> >
> > --
> > You received this message because you are subscribed to the Google
> Groups "sphinx-dev" group.
> > To post to this group, send email to sphin...@googlegroups.com
> .
> > To unsubscribe from this group, send email to
> sphinx-dev+...@googlegroups.com .
> > For more options, visit this group at
> http://groups.google.com/group/sphinx-dev?hl=en
> .
> >
> 
> -- 
> You received this message because you are subscribed to the Google
> Groups "sphinx-dev" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/sphinx-dev/-/7Xgdn5bp2hQJ.
> To post to this group, send email to sphinx-dev@goog

Re: [sphinx-dev] Annoucing robin, a new Doxygen to Sphinx bridge

[Michael Gielda]

Hi Anteru,

Firstly, a big thanks for answering in such detail, it is nice to have a 
good understanding of your intentions and motivations :)

I think that yours is a bit different of a use case than ours and in a 
sense I can see that you may need a different project for that kind of 
stuff.

We are using breathe for a mixed language project, but to be able to 
illustrate uses with examples etc. rather than providing full 
documentation, at least at the moment.

For doing 'fully automatic' stuff we just use Doxygen - it can generate 
neat stuff if you (and especially your customers) need it. I think Sphinx 
is not meant for such things anyway, I mean it would be nice to be able to 
do that, why not, but good Sphinx docs can't be automatic, they need the 
human attention. Though I do remember forcing breathe to generate docs for 
an entire class, so doing a whole project should not be so terrible if you 
had to. 

What is for me a downside of your solution is the mongodb - one more 
service you need to run, one more thing that can break :)

Still, congratulations on an ambitious project and for contributing it to 
the community - and under BSD, nice!

Best,
Michael

On Saturday, 1 September 2012 21:15:07 UTC+2, Anteru wrote:
>
> Hi, 
>
> we did try Breathe actually; the main problem we had with it was that we 
> couldn't hack the output easily and that there was no "automodule" 
> support in it to generate documentation for all files in a project. Our 
> goal was to make a minimal bridge which is easy to hack, so anything 
> that is missing can be added easily, and to abstract away from Doxygen 
> as quickly as possible. 
>
> There's still some stuff which can be implemented better in Robin (for 
> instance, we currently need two passes over the generated .rst files) 
> but our feeling is that hacking Robin to get it working will be easier 
> than hacking Breathe. If you take a look at Robin, it's cleanly 
> separated into one pass which converts from Doxygen to MongoDB, and a 
> second pass which works on well-structured data. We did actually a split 
> on the development side, with one author writing each of the parts :) 
>
> That's however our personal view, and so far, we do generate the 
> documentation for a large C++ project with it and we're happy. If 
> there's anything we can do to make the code more accessible, feel free 
> to drop us a line. 
>
> Cheers 
>
> Am 28.08.2012 22:51, schrieb Michael Gielda: 
> > Hi, 
> > 
> > My thoughts exactly, Michael, I use your Breathe extension and most of 
> > the stuff just works... gotta test if the new thing provides more 
> > functionality but perhaps the authors can point us in the right 
> direction? 
> > I mean Breathe is not ideal but perhaps it would be wiser to fill in the 
> > blanks than write a new framework from scratch. Still, if it is there, 
> > perhaps they can benefit mutually from the 'competition'? 
> > 
> > Best, 
> > Michael (it's a fairly popular name ;) ) 
> > 
> > On Sunday, 26 August 2012 00:18:01 UTC+2, mpj wrote: 
> > 
> > Hey, 
> > 
> > I wrote Breathe, if you'd be up for providing a short explanation of 
> > why you started your project and what advantages you feel your 
> > approach has then I'd love to put it in the Breathe readme so that 
> > people can see alternatives. 
> > 
> > Cheers, 
> > Michael 
> > 
> > On Sat, Jun 16, 2012 at 3:59 AM, Anteru 
> > > wrote: 
> > > Hi, 
> > > 
> > > We're happy to announce robin, a new Doxygen/C++ to Sphinx bridge. 
> > Robin 
> > > provides an easy-to-use, easy-to-hack integration of Doxygen 
> > > documentation into Sphinx. Robin is licensed under the BSD and can 
> be 
> > > found at Bitbucket: https://bitbucket.org/reima/robin 
> >  
> > > 
> > > Features 
> > >  
> > > 
> > > * Robust extraction of Doxygen XML data via an easy-to-hack parser 
> > > * Intermediate data is stored in a database (mongodb) for simple 
> > > extraction and processing 
> > > * Directive-driven output; each directive provides callbacks and 
> > hooks 
> > > which allows for deep customization 
> > > * Automated generation of driver ReST documents: Similar to 
> > automodule; 
> > > however, robin generates actual ReST documents which can be 
> inspected 
> > > 
> > > Prerequisites 
> > > = 
> > > 
> > > Robin expects a running mongodb on the local host. It uses a 
> > minimal set 
> > > of external libraries: Pymongo, sphinx, progressbar. All of the 
> > > dependencies can be easily installed using pip or easy_install. 
> > > 
> > > Robin has been developed with Python 2.7; we have not tested 
> previous 
> > > versions. 
> > > 
> > > Getting started 
> > > === 
> > > 
> > > * Run Doxygen to generate XML documentation (GENERATE_XML=YES) 
> > > * Run extra

[sphinx-dev] Adding projects to examples page

[Ryan Galloway]

Greetings,

Per the examples page at http://sphinx.pocoo.org/examples.html, I'm
emailing the group to inquire about adding a couple of (small)
projects hosted on github to the list:

http://rsgalloway.github.com/pyseq/
http://rsgalloway.github.com/grit/docs/
http://rsgalloway.github.com/QRangeSlider/

Thanks for your consideration,

Ryan

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.