New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switch python docs from doxygen to Sphinx. #160

Open
barnabytprowe opened this Issue May 21, 2012 · 18 comments

Comments

Projects
None yet
6 participants
@barnabytprowe
Member

barnabytprowe commented May 21, 2012

This is a question Jim brought up on the code list early on, and I think it's appropriate now to think about it again.

Over to Jim:

"When we have C++ code with Python bindings, there are a couple places we can put the documentation:

  • In the Doxygen comments, which come from the C++ header files and describe the C++ interface.
  • In the Python docstrings and interactive help, which comes from strings embedded in the Boost.Python wrapper code.

If we really want to do this properly, I think the content in both of those places is slightly different, because they describe slightly different things. But there's going to be a huge amount of overlap and duplication, and it could be a lot of work to make sure they're both up to date and that important information is present in both places.

Moreover, because Doxygen parses the Python source (rather than inspecting the Python docstrings), there's no way (that I know of) to get the Python interface documentation for wrapped classes into Doxygen.

Overall, while I like Doxygen quite a bit for C++, I wonder whether we'd be better off focusing on the docstrings as the canonical documentation for Python (and maybe not even running Doxygen on Python). Doxygen makes a point of not actually parsing some of its own markup in Python docstrings, so people aren't forced to make their docstrings look weird when viewed naturally by filling them with Doxygen markup, so I'm not sure we're getting that much from Python-side Doxygen. And if using Doxygen with Python does mean that we have to put weird markup that disturbs the natural docstrings, do we want that?

I noticed a "doxypy" file that seems to be intended to address some of these problems. Does it? If so, could we adapt it to work on the Boost.Python outputs too?

(Barney's note: Joe thought that the answer to this question would be that getting doxypy to do this might be difficult. Probably not impossible.)

I've also heard good things about using Sphinx to document Python, but I don't have any direct experience with it. Does anyone else?

(Barney's note: no-one really stepped forward on this one, so I guess the answer is no)."

I think it's maybe time to revisit this issue, and get some opinions.

Currently there are absolutely key pieces of the Python interface that are documented in the C++ wrapping and thus these docstrings are not exposed to doxygen, and thus don't make it into the doxygen docs as far as I can see.

One option for this might be to rename the C++ wrapper classes and move the current class definitions into pure Python, and thus define the docstrings in .py module files so they are read in (we already add some methods at the Python level for some classes, so this would not represent such a vast change albeit a fairly fundamental one). Would this work? Other options may be available, and all of this of course presupposes the desire to continue to use doxygen for Python, which Jim questioned and I think is worth discussing.

Also, as Jim points out, some of the doxygen markup even in the direct Python code looks pretty ugly when viewed naturally (e.g. using ipython or print <thing>.__doc__) and it's not clear how much of this syntax is necessary given some of the automatic processing that doxygen seems to do.

Points / thoughts / additions / comments for these questions would be welcomed.

@TallJimbo

This comment has been minimized.

Show comment
Hide comment
@TallJimbo

TallJimbo May 21, 2012

Member

Since then, I've tinkered with Sphinx just a little, and it was very easy to set up, though I didn't try to do anything fancy with it. It also produces very nice-looking documentation that's very familiar to Python users (it's what is used to make the Python official documentation and matplotlib, for instance).

More importantly, I also found out that it operates by importing the Python modules and looking for the docstrings there, which is exactly what we want.

All that makes me think that we should use continue to use Doxygen for C++ (which it does very well), and add Sphinx to do the documentation for the Python and Boost.Python code. My hope is that this is just a matter of getting Sphinx running as part of the build system; because it looks at our actual Python interface (not how we implemented it), we should get clean documentation mostly just by having a clean interface.

I probably shouldn't volunteer to do too much work on it myself, I'm afraid, given what happened to my small commitments on the last milestone and the other aspects of GalSim I'd like to devote my little GalSim development time to, but I do think this is the approach we should take.

Member

TallJimbo commented May 21, 2012

Since then, I've tinkered with Sphinx just a little, and it was very easy to set up, though I didn't try to do anything fancy with it. It also produces very nice-looking documentation that's very familiar to Python users (it's what is used to make the Python official documentation and matplotlib, for instance).

More importantly, I also found out that it operates by importing the Python modules and looking for the docstrings there, which is exactly what we want.

All that makes me think that we should use continue to use Doxygen for C++ (which it does very well), and add Sphinx to do the documentation for the Python and Boost.Python code. My hope is that this is just a matter of getting Sphinx running as part of the build system; because it looks at our actual Python interface (not how we implemented it), we should get clean documentation mostly just by having a clean interface.

I probably shouldn't volunteer to do too much work on it myself, I'm afraid, given what happened to my small commitments on the last milestone and the other aspects of GalSim I'd like to devote my little GalSim development time to, but I do think this is the approach we should take.

@barnabytprowe

This comment has been minimized.

Show comment
Hide comment
@barnabytprowe

barnabytprowe Sep 20, 2012

Member

Paraphrased from the discussion on #253/#236:

There is one issue that came up which is not fixed on #236. The problem is that a number of our python modules are actually defined as classes in galsim/_galsim.so and we add things like docstrings and extra methods later. Examples are the classes in...

  • image.py
  • bounds.py
  • angle.py
  • random.py
  • position.py

To get these into doxygen (which I think we want to do) we need to find a way to bring their actual class definition into the Python layer, perhaps by inheriting from or containing the current wrapped C++ classes. There was a bit of discussion of this in #236. Whatever changes we make to these classes in Python, we should update the GalSim Quick Ref to include the hyperlinks that will subsequently become available to doxygen-ized docstrings.

Thinking about it, the only way I can imagine doing this so that doxygen would be able to fully parse all the class and method information would be to make Python layer classes containers for the wrapped C++, and write each method anew at the Python layer but have its contents be a simple redirect to the C++, for example:

    def method_name(self, args*, kwargs**):
        """Docstring already at Python layer
        """
        return self._CClass_name.method_name(args*, kwargs**)

... if that makes sense?

I'd thought that maybe we could simple inherit from the wrapped C++ classes, but a) Jim had reservations about this in the past with Boost.Python and b) Doxygen wouldn't be able to see all the methods properly anyway.

@rmandelb and I are not convinced this is of massive urgency for the upcoming release (what is said on #236 for example is accurate, if not as slick as it could be, about how / where to find docstrings). But we would love thoughts about the idea above to get the classes above into doxygen soon.

Member

barnabytprowe commented Sep 20, 2012

Paraphrased from the discussion on #253/#236:

There is one issue that came up which is not fixed on #236. The problem is that a number of our python modules are actually defined as classes in galsim/_galsim.so and we add things like docstrings and extra methods later. Examples are the classes in...

  • image.py
  • bounds.py
  • angle.py
  • random.py
  • position.py

To get these into doxygen (which I think we want to do) we need to find a way to bring their actual class definition into the Python layer, perhaps by inheriting from or containing the current wrapped C++ classes. There was a bit of discussion of this in #236. Whatever changes we make to these classes in Python, we should update the GalSim Quick Ref to include the hyperlinks that will subsequently become available to doxygen-ized docstrings.

Thinking about it, the only way I can imagine doing this so that doxygen would be able to fully parse all the class and method information would be to make Python layer classes containers for the wrapped C++, and write each method anew at the Python layer but have its contents be a simple redirect to the C++, for example:

    def method_name(self, args*, kwargs**):
        """Docstring already at Python layer
        """
        return self._CClass_name.method_name(args*, kwargs**)

... if that makes sense?

I'd thought that maybe we could simple inherit from the wrapped C++ classes, but a) Jim had reservations about this in the past with Boost.Python and b) Doxygen wouldn't be able to see all the methods properly anyway.

@rmandelb and I are not convinced this is of massive urgency for the upcoming release (what is said on #236 for example is accurate, if not as slick as it could be, about how / where to find docstrings). But we would love thoughts about the idea above to get the classes above into doxygen soon.

@barnabytprowe

This comment has been minimized.

Show comment
Hide comment
@barnabytprowe

barnabytprowe Oct 4, 2012

Member

Hi all,

I'm pinging on this again to get an opinion, especially calling all of our leading documentation writers, helpers and general developers ( @joezuntz , @joergdietrich , @rmjarvis , @rmandelb , @TallJimbo , @pmelchior , @mssgill , @tomaszkacprzak , @rearmstr , @reikonakajima ).

Currently there are large parts of the Python code not visible through DOxygen, as described in the post above.

  1. Is this a big problem?
  2. Is it a big enough problem to go to the trouble of making new container classes at the Python layer for all the C++ functionality?
  3. Can we think of a better option than 2.?

Opinions solicited and will be gratefully received!

Member

barnabytprowe commented Oct 4, 2012

Hi all,

I'm pinging on this again to get an opinion, especially calling all of our leading documentation writers, helpers and general developers ( @joezuntz , @joergdietrich , @rmjarvis , @rmandelb , @TallJimbo , @pmelchior , @mssgill , @tomaszkacprzak , @rearmstr , @reikonakajima ).

Currently there are large parts of the Python code not visible through DOxygen, as described in the post above.

  1. Is this a big problem?
  2. Is it a big enough problem to go to the trouble of making new container classes at the Python layer for all the C++ functionality?
  3. Can we think of a better option than 2.?

Opinions solicited and will be gratefully received!

@reikonakajima

This comment has been minimized.

Show comment
Hide comment
@reikonakajima

reikonakajima Oct 4, 2012

Member

For me, I've learn to go through the *.py docstrings, so I'm not even aware what's not visible through DOxygen.
I can see that it can be frustrating, though, if ones primary means to understand the code is with DOxygen.
As for #3, I am not aware of a better alternative (sorry).

Member

reikonakajima commented Oct 4, 2012

For me, I've learn to go through the *.py docstrings, so I'm not even aware what's not visible through DOxygen.
I can see that it can be frustrating, though, if ones primary means to understand the code is with DOxygen.
As for #3, I am not aware of a better alternative (sorry).

@TallJimbo

This comment has been minimized.

Show comment
Hide comment
@TallJimbo

TallJimbo Oct 4, 2012

Member

I too generally look at code rather than Doxygen, so it's not a big issue for me personally.

I don't like the idea of modifying our code simply to unconfuse our documentation-generator.

In the category of other solutions, I think it makes a lot of sense to have separate C++ API documentation (through Doxygen) and Python documentation, and I think Sphinx (http://sphinx.pocoo.org/) is very much worth a look for the latter. Unlike Doxygen, it generates documentation by importing Python modules and looking at the docstrings, rather than trying to re-parse the Python code with a custom parser. It's just a much smarter approach overall.

Member

TallJimbo commented Oct 4, 2012

I too generally look at code rather than Doxygen, so it's not a big issue for me personally.

I don't like the idea of modifying our code simply to unconfuse our documentation-generator.

In the category of other solutions, I think it makes a lot of sense to have separate C++ API documentation (through Doxygen) and Python documentation, and I think Sphinx (http://sphinx.pocoo.org/) is very much worth a look for the latter. Unlike Doxygen, it generates documentation by importing Python modules and looking at the docstrings, rather than trying to re-parse the Python code with a custom parser. It's just a much smarter approach overall.

@rmjarvis

This comment has been minimized.

Show comment
Hide comment
@rmjarvis

rmjarvis Oct 4, 2012

Member

I suspect we should wait until we have people who do use Doxygen regularly and query them whether they think it's a problem, and if so whether they would prefer having two separate documentation systems for c++ and python or if that would be even worse than the current situation. My guess is that our non-doxygen documentation (the GettingStarted guide, the Config Documentation, other wiki pages) will be much more useful than the doxygen pages, so I don't think we should spend a lot of effort getting them improved. (As opposed to our recent effort on the doc strings which I think was useful.)

Member

rmjarvis commented Oct 4, 2012

I suspect we should wait until we have people who do use Doxygen regularly and query them whether they think it's a problem, and if so whether they would prefer having two separate documentation systems for c++ and python or if that would be even worse than the current situation. My guess is that our non-doxygen documentation (the GettingStarted guide, the Config Documentation, other wiki pages) will be much more useful than the doxygen pages, so I don't think we should spend a lot of effort getting them improved. (As opposed to our recent effort on the doc strings which I think was useful.)

@rmandelb

This comment has been minimized.

Show comment
Hide comment
@rmandelb

rmandelb Oct 7, 2012

Member

I think that what Mike is saying makes sense. By the time we get to the workshop, we should have at least a few people (who haven't been actively coding) look at the code. We can ask them about this specific point there, and make a decision at that time. I agree with Jim, though, that this alone seems like insufficient reason to make python containers for C++ objects.

Member

rmandelb commented Oct 7, 2012

I think that what Mike is saying makes sense. By the time we get to the workshop, we should have at least a few people (who haven't been actively coding) look at the code. We can ask them about this specific point there, and make a decision at that time. I agree with Jim, though, that this alone seems like insufficient reason to make python containers for C++ objects.

@barnabytprowe

This comment has been minimized.

Show comment
Hide comment
@barnabytprowe

barnabytprowe Oct 7, 2012

Member

OK, thanks for the input guys, very happy to let this wait for a while. I'll take a look at Sphynx too Jim: it is a nice system, and its look and feel is very familiar to Python users.

Member

barnabytprowe commented Oct 7, 2012

OK, thanks for the input guys, very happy to let this wait for a while. I'll take a look at Sphynx too Jim: it is a nice system, and its look and feel is very familiar to Python users.

@barnabytprowe

This comment has been minimized.

Show comment
Hide comment
@barnabytprowe

barnabytprowe Jan 2, 2013

Member

Hi all. I closed issue #259 (Distinguishing between c++ and Python in the dox) to bring that here, as we're essentially now talking about the same thing on this issue.

I quote from Rachel in the preamble to #259:

As Mike pointed out on pull request #249, it would be nice if the doxygen documentation clearly indicated which are C++ classes and which are python. I noticed that on my Mac, with doxygen 1.8.0, this difference is clearly indicated (e.g., galsim::integ for C++ vs. galsim.base for python) but this seems to be particular to 1.8.0, since Jenkins has 1.8.1 and doesn't distinguish between them.

Joe mentioned that we could simply have separate documentation generated for the C++ and python parts of galsim, but that seems sub-optimal to me. People are going to say things like "Oh, the Gaussian class contains an SBGaussian, let me look at the documentation for that" and it would be weird (IMO) if that took them to completely separate documents.

Likewise it seems suboptimal to force Jenkins to doxygen 1.8.0.

And having to redo the dox everywhere to clearly state that the class in question is C++ or python would be really annoying.

This issue is for further discussion of this point: whether we want to do something about it, and if so, what? Perhaps it's not a matter of doxygen version but rather some setting somewhere that could be used to distinguish between them for any doxygen version?

Um, and I failed to put my question, which is: do you agree that we should table this issue for now and ask users about it later?

This proposal was agreed to, and since then we've had no adverse feedback about the documentation. In fact, people have generally been complimentary about the state of the documentation for GalSim, although we've not had direct feedback on the C++/Python separation issue.

Moving to Sphinx for the Python layer, or rather investigating this, is basically the current best suggestion to remedy the issues raised in both #160 and #259. We should leave at least one issue open to explore this long term, and I guess this is it!

Member

barnabytprowe commented Jan 2, 2013

Hi all. I closed issue #259 (Distinguishing between c++ and Python in the dox) to bring that here, as we're essentially now talking about the same thing on this issue.

I quote from Rachel in the preamble to #259:

As Mike pointed out on pull request #249, it would be nice if the doxygen documentation clearly indicated which are C++ classes and which are python. I noticed that on my Mac, with doxygen 1.8.0, this difference is clearly indicated (e.g., galsim::integ for C++ vs. galsim.base for python) but this seems to be particular to 1.8.0, since Jenkins has 1.8.1 and doesn't distinguish between them.

Joe mentioned that we could simply have separate documentation generated for the C++ and python parts of galsim, but that seems sub-optimal to me. People are going to say things like "Oh, the Gaussian class contains an SBGaussian, let me look at the documentation for that" and it would be weird (IMO) if that took them to completely separate documents.

Likewise it seems suboptimal to force Jenkins to doxygen 1.8.0.

And having to redo the dox everywhere to clearly state that the class in question is C++ or python would be really annoying.

This issue is for further discussion of this point: whether we want to do something about it, and if so, what? Perhaps it's not a matter of doxygen version but rather some setting somewhere that could be used to distinguish between them for any doxygen version?

Um, and I failed to put my question, which is: do you agree that we should table this issue for now and ask users about it later?

This proposal was agreed to, and since then we've had no adverse feedback about the documentation. In fact, people have generally been complimentary about the state of the documentation for GalSim, although we've not had direct feedback on the C++/Python separation issue.

Moving to Sphinx for the Python layer, or rather investigating this, is basically the current best suggestion to remedy the issues raised in both #160 and #259. We should leave at least one issue open to explore this long term, and I guess this is it!

@rmjarvis rmjarvis changed the title from Revisiting the question of Python (and particularly Boost.Python) with doxygen docstrings to Switch python docs from doxygen to Sphinx. Jan 6, 2017

@rmjarvis

This comment has been minimized.

Show comment
Hide comment
@rmjarvis

rmjarvis Jan 6, 2017

Member

I updated the title of this to "Switch python docs from doxygen to Sphinx". I'm convinced that this would be a much nicer form of documentation than what we currently have, which is a bit unwieldy imo.

Plus, we can even move all the stuff that is currently in the Quick Reference Guide into the main docs, since you can add whatever custom doc pages you want in Sphinx very easily. Probably some of the wiki pages could also be incorporated. (I'm particularly thinking of the config layer docs.) This would be a lot nicer than having multiple locations for documentation for people to look at. And it would automatically handle all the hyperlinks for us.

I don't particularly have time to do this, but I'm hoping that changing the name of the issue might encourage someone to give it a try. And I'd be happy to help, since I've done Sphinx docs for TreeCorr, and it's what we're using for Piff, so I have some familiarity with them.

Member

rmjarvis commented Jan 6, 2017

I updated the title of this to "Switch python docs from doxygen to Sphinx". I'm convinced that this would be a much nicer form of documentation than what we currently have, which is a bit unwieldy imo.

Plus, we can even move all the stuff that is currently in the Quick Reference Guide into the main docs, since you can add whatever custom doc pages you want in Sphinx very easily. Probably some of the wiki pages could also be incorporated. (I'm particularly thinking of the config layer docs.) This would be a lot nicer than having multiple locations for documentation for people to look at. And it would automatically handle all the hyperlinks for us.

I don't particularly have time to do this, but I'm hoping that changing the name of the issue might encourage someone to give it a try. And I'd be happy to help, since I've done Sphinx docs for TreeCorr, and it's what we're using for Piff, so I have some familiarity with them.

@rmjarvis rmjarvis modified the milestones: v1.6, v2.0 Jun 23, 2017

@ofloveandhate

This comment has been minimized.

Show comment
Hide comment
@ofloveandhate

ofloveandhate Oct 5, 2017

i, too, struggle with maintaining a single set of documentation for a C++ library, and a Python module. Did your group fully switch to Sphinx?

My project is bertini2, a polynomial system solver, and I simply can't afford the upkeep on multiple sources of documentation -- in C++ doxygen comments, in markdown pages passed to doxygen, in python docstrings in my C++ boost.python code, in tests for both pieces, ... I desperately need help getting this all unified. Any tips from your team are appreciated! I found your issue by googling "generate documentation for python package built using boost.python"

ofloveandhate commented Oct 5, 2017

i, too, struggle with maintaining a single set of documentation for a C++ library, and a Python module. Did your group fully switch to Sphinx?

My project is bertini2, a polynomial system solver, and I simply can't afford the upkeep on multiple sources of documentation -- in C++ doxygen comments, in markdown pages passed to doxygen, in python docstrings in my C++ boost.python code, in tests for both pieces, ... I desperately need help getting this all unified. Any tips from your team are appreciated! I found your issue by googling "generate documentation for python package built using boost.python"

@rmjarvis

This comment has been minimized.

Show comment
Hide comment
@rmjarvis

rmjarvis Oct 5, 2017

Member

We're actually in the process of ditching boost python (switching to either pybind11 or cffi). But we haven't switched over to Sphinx yet.

All our public API is really the Python layer, so I think we're mostly fine with having the public docs only parse the python stuff and use Sphinx for that. Then leave the doxygen markup in C++ for developer information, but not really worry much about making it look pretty, since users won't care about it.

Member

rmjarvis commented Oct 5, 2017

We're actually in the process of ditching boost python (switching to either pybind11 or cffi). But we haven't switched over to Sphinx yet.

All our public API is really the Python layer, so I think we're mostly fine with having the public docs only parse the python stuff and use Sphinx for that. Then leave the doxygen markup in C++ for developer information, but not really worry much about making it look pretty, since users won't care about it.

@ofloveandhate

This comment has been minimized.

Show comment
Hide comment
@ofloveandhate

ofloveandhate Oct 5, 2017

thanks for the quick response. i'm trying to try out sphinx now.

i'm not deeply committed to boost.python, except for my small teamsize. is your motivation for switching at all the docstrings, or documentation? one hurdle i am overcoming is that the docstrings in my module using boost.python are compiled in -- so that changing documentation requires recompiling. i don't like it. i mean, in C++ doxygen it's the same thing, but... maybe you know a way around?

ofloveandhate commented Oct 5, 2017

thanks for the quick response. i'm trying to try out sphinx now.

i'm not deeply committed to boost.python, except for my small teamsize. is your motivation for switching at all the docstrings, or documentation? one hurdle i am overcoming is that the docstrings in my module using boost.python are compiled in -- so that changing documentation requires recompiling. i don't like it. i mean, in C++ doxygen it's the same thing, but... maybe you know a way around?

@rmjarvis

This comment has been minimized.

Show comment
Hide comment
@rmjarvis

rmjarvis Oct 5, 2017

Member

No, the reason is mostly to make it easier for people to install the code. By far our biggest source of trouble with installation is the boost dependency.

But, I'll point out that you don't need to do the python documentation in C++ for the boost-wrapped classes. We add in a lot of documentation in python. See for instance our Angle class:

https://github.com/GalSim-developers/GalSim/blob/releases/1.4/galsim/angle.py

For the classes, you can just assign to the __doc__ attribute. e.g. Angle.__doc__ = """Some documentation...""". Methods are a little trickier if you care about working in both Python 2 and 3, since the syntax changed. We have a helper function for that called set_func_doc.

Member

rmjarvis commented Oct 5, 2017

No, the reason is mostly to make it easier for people to install the code. By far our biggest source of trouble with installation is the boost dependency.

But, I'll point out that you don't need to do the python documentation in C++ for the boost-wrapped classes. We add in a lot of documentation in python. See for instance our Angle class:

https://github.com/GalSim-developers/GalSim/blob/releases/1.4/galsim/angle.py

For the classes, you can just assign to the __doc__ attribute. e.g. Angle.__doc__ = """Some documentation...""". Methods are a little trickier if you care about working in both Python 2 and 3, since the syntax changed. We have a helper function for that called set_func_doc.

@ofloveandhate

This comment has been minimized.

Show comment
Hide comment
@ofloveandhate

ofloveandhate Oct 5, 2017

can i sum up?

you're moving to sphinx for documentation of your python bindings, but moving generation of the python bindings from C++ from Boost.Python to another binding library such as pybind11 or cffi.

  1. you have core c++ code in src,
  2. and code which generates python bindings in pysrc.
  3. the Boost.Python (or other) generated python bindings are not directly exposed to the user,
  4. but instead there's another layer of pure python code which forms the raw bindings into nice modules. it lives in GalSim/galsim.
  5. that's where your primary documentation lives -- in the python code that finally wraps the raw bindings and other libraries together.

is that about right? so that moving to sphinx is orthogonal to the move away from Boost.Python, because you would still parse about the same files in the same folders (GalSim/galsim)?

deeply appreciatively, ofloveandhate

ofloveandhate commented Oct 5, 2017

can i sum up?

you're moving to sphinx for documentation of your python bindings, but moving generation of the python bindings from C++ from Boost.Python to another binding library such as pybind11 or cffi.

  1. you have core c++ code in src,
  2. and code which generates python bindings in pysrc.
  3. the Boost.Python (or other) generated python bindings are not directly exposed to the user,
  4. but instead there's another layer of pure python code which forms the raw bindings into nice modules. it lives in GalSim/galsim.
  5. that's where your primary documentation lives -- in the python code that finally wraps the raw bindings and other libraries together.

is that about right? so that moving to sphinx is orthogonal to the move away from Boost.Python, because you would still parse about the same files in the same folders (GalSim/galsim)?

deeply appreciatively, ofloveandhate

@rmjarvis

This comment has been minimized.

Show comment
Hide comment
@rmjarvis

rmjarvis Oct 5, 2017

Member

Yes. Mostly correct anyway.

The two efforts are definitely orthogonal. And we haven't actually started any effort to move to Sphinx. It's just on our wish list for once someone has the time to devote to it. :)

Also, some of the classes that we currently expose with boost python are the things visible to the user. E.g. Angle. Most of the methods and such are defined in C++. Then in python, we add on some documentation along with a few additional methods that were easier to write in python. But you'll notice that there is no class Angle specification in angle.py. It's just imports Angle from ._galsim, which is the compiled C++ library.

Hope this is helpful for your project.

Member

rmjarvis commented Oct 5, 2017

Yes. Mostly correct anyway.

The two efforts are definitely orthogonal. And we haven't actually started any effort to move to Sphinx. It's just on our wish list for once someone has the time to devote to it. :)

Also, some of the classes that we currently expose with boost python are the things visible to the user. E.g. Angle. Most of the methods and such are defined in C++. Then in python, we add on some documentation along with a few additional methods that were easier to write in python. But you'll notice that there is no class Angle specification in angle.py. It's just imports Angle from ._galsim, which is the compiled C++ library.

Hope this is helpful for your project.

@ofloveandhate

This comment has been minimized.

Show comment
Hide comment
@ofloveandhate

ofloveandhate Jan 16, 2018

i thank you again for your help last year. my c++ library exposed through boost.python and documented using sphinx is much improved thanks to you. i credited GalSim and this issue in my comments where I used your help.

I am totally loving Sphinx for my Python documentation

🌺

ofloveandhate commented Jan 16, 2018

i thank you again for your help last year. my c++ library exposed through boost.python and documented using sphinx is much improved thanks to you. i credited GalSim and this issue in my comments where I used your help.

I am totally loving Sphinx for my Python documentation

🌺

@rmjarvis

This comment has been minimized.

Show comment
Hide comment
@rmjarvis

rmjarvis Jan 16, 2018

Member

Cheers. :)

Member

rmjarvis commented Jan 16, 2018

Cheers. :)

@rmjarvis rmjarvis modified the milestones: v2.0, v2.1 Apr 21, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment