I have tried both forms of introducing code, and fairly quickly settled on
using not the method you do, but this one:
This function requires some explanation:
.. code-block:: python
def alsoHard(self):
print "Success"
As you can see, this function requires careful handling.
I found that maintaining my docs over even just the few weeks I took making
this decision, the explicit "code-block" form had several advantages I
wanted:
- It was easier to notice problems from the output and quickly tie them to
problems in the docs (finding that trailing double-colon proved in some
cases to be "invisible").
- It was easier for me to easily represent various kinds of code examples
(which, admittedly, my docs needs, but yours might not)
- It helped me visually account for where every block needed to be indented
as I worked
- It explicitly reminded me what the language was for the code example
Your mileage may vary, and I realize it doesn't directly address your issue.
In Emacs, there are functions in the restructured text editing mode to
block indent and outdent a region of text, which has proved useful. Of
course, that only helps you out if you're using Emacs...
--
V.
On Tuesday, 6 March 2012 14:15:36 UTC-5, nicky wrote:
>
> Hi,
>
> I just joined this group. Thanks for making sphinx available. It makes
> it very easy to make my code available on the web.
>
> I have a question about keeping indentation in an entire code block. I
> would like to add documentation in between class methods, like so:
>
>
> introduction
> ==================
>
> ::
>
> class LongClass():
> def hardFunction(self):
> return 3
>
> This function requires substantial explanation
>
> ::
>
> def alsoHard(self):
> print "success"
>
>
> More explanations requiring mathematics.
>
> ::
>
> def simple(self):
> print "aha"
>
> End of rst file
> ----------------------
>
>
> The problem is that in the html file the methods are not indented
> anymore, see http://nicky.vanforeest.com/mg1StateProbabilities/hank.html.
> Now, due to the removed indentation, the methods seem to have become
> functions. Is there any way to repair this in the rst file?
>
> Thanks
>
> Nicky
>
>
--
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/-/bhk6OBrDLUQJ.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
