Make sphinx use docutils.conf

[Kam]

Hi there,

I have a question regarding docutils configuration to control the HTML output generated by sphinx.

My question is identical to the unanswered question on Stack Overflow, found here: http://stackoverflow.com/questions/13029207/overriding-the-default-field-name-limit-in-sphinx-docutils

I want to change the way that tables are printed when listing command line options. There is an option for that in docutils called option_limit and I put it in my docutils configuration file in my root sphinx documentation directory:

cat docutils.conf 

[general]

dump_settings:1

dunmp_internals:1

[html4css1 writer]

# This makes options span two columns when printed in HTML.

option-limit:1

Thanks to "dump_internals" and "dump_settings", I can see all of the options, including "option-limit", and their values when I execute make html

However, the generated HTML output does not change when I change the "option-limit".

How can I make sphinx use the docutils.conf values when generating HTML output?

Please let me know if you need additional information from me to help solve this problem.

[Takayuki Shimizukawa]

Hi Kam,

Sphinx does not support docutils.conf.
# I couldn't find any sign why docutils.conf hadn't been supported by Sphinx.

I changed Sphinx to read the docutils.conf file in the code repository.
Please check it out and report if you can.
https://bitbucket.org/birkenfeld/sphinx/commits/67682aca

Regards,
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa


2013/5/26 Kam <kslowi...@gmail.com>:

> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sphinx-dev+...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

[Kamil Slowikowski]

Hi Takayuki,

Thank you for the commit! I appreciate your help.

I tested the new sphinx and it does not seem to work.

Perhaps the option-limit option does not do what I think it does? I expect that setting it to 1 will force all elements with class="option-group" to span two columns with colspan="2". Below, you can see the first two options do not span two columns and the third option does. I want all three of them to have colspan="2".

<tbody valign="top">
	<tr><td class="option-group">
	<kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
	<td>Print this help message and exit.</td></tr>
	<tr><td class="option-group">
	<kbd><span class="option">-v</span>, <span class="option">--version</span></kbd></td>
	<td>Print version and exit.</td></tr>
	<tr><td class="option-group" colspan="2">
	<kbd><span class="option">-s</span>, <span class="option">--snps <var>FILE</var></span></kbd></td>
	</tr>
	<tr><td>&nbsp;</td><td>List of SNPs to test.</td></tr>

python -c 'import sphinx; print sphinx.__version__'

1.2b1

Kam

[Takayuki Shimizukawa]

Hi Kam,

How did you install the Sphinx?

The change is not included in released version then you need install from code repository.

--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa

2013/7/27 Kamil Slowikowski <kslowi...@gmail.com>

--

[Kamil Slowikowski]

I installed it with

hg clone ssh://h...@bitbucket.org/birkenfeld/sphinx

cd sphinx

python setup.py --user

and it seems to have installed properly

python -c 'import sphinx,sys; print sphinx.__version__, sys.path'

1.2b1 ['', '/home/kamil/.local/lib/python2.7/site-packages/Sphinx-1.2b1dev_20130726-py2.7.egg' ...

[gilberto dos santos alves]

please to be sure that you are using correct path see your env var
PYTHONPATH, and import path; for whatis in sys.path: print whatis

because many times there are some lib and places before $HOME/.local

2013/7/26 Kamil Slowikowski <kslowi...@gmail.com>:

> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sphinx-dev+...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

--
gilberto dos santos alves
+55.11.98646-5049
sao paulo - sp - brasil

[Kamil Slowikowski]

Hi Gilberto,

I have already shown the first two entries in my sys.path. Are you suggesting something different?

[gilberto dos santos alves]

i have problems using this on centos, where i do not is root user.
(python 2.7.3 and django 1.6b1) reason was easy_install / pip (not
handled very well pre release versions). now easy_install has clause
--pre .
i used python setup.py install and for users and places that is at
/home/some-users/.local i my opinion there are some bugs. only when i
clear sys.path and i have manually sys.path.append libs and dirs all
things worked very well.

2013/7/26 Kamil Slowikowski <kslowi...@gmail.com>:

> Hi Gilberto,
>
> I have already shown the first two entries in my sys.path. Are you
> suggesting something different?
>

[Kamil Slowikowski]

I can confirm that the correct sphinx is used with sphinx.__file__:

python -c 'import sphinx, sys; print sphinx.__version__, sphinx.__file__, sys.path'

1.2b1 /home/kamil/.local/lib/python2.7/site-packages/Sphinx-1.2b1dev_20130726-py2.7.egg/sphinx/__init__.pyc ['', '/home/kamil/.local/lib/python2.7/site-packages/Sphinx-1.2b1dev_20130726-py2.7.egg',

[Takayuki SHIMIZUKAWA]

Hi,

It works fine in my environment.

I added unittest to verify html output with using docutils.conf and it passed in some environment:
https://bitbucket.org/birkenfeld/sphinx/src/e34ebe4/tests/test_docutilsconf.py#cl-53

docutils.conf loading point is here:
https://bitbucket.org/birkenfeld/sphinx/src/e34ebe4/sphinx/builders/html.py#cl-261
If you can, check the value of self.docsettings.option_imit in this line.


# BTW "dump_internals" and "dump_settings" is useful but not
# helpful in sphinx, because sphinx writers did not use docutils
# Publisher.publish() that emit dumps.

Regards,