[sphinx-users] Re: Discover new Document on a Subdir

[Peter Burdine]

Marco,

Are you looking for globbing in the toctree?  Eg:

.. toctree::
:glob:


DIR1/*
DIR2/*
DIR3/*


This will include ALL the files from DIR1 (sorted in alphanumeric order) 
then DIR2 then DIR3, etc.

--Peter

On Thursday, April 23, 2020 at 7:11:49 AM UTC-7, Marco Longo wrote:
>
> Hi comunity,
>
> I'm almost new and so my question should be not so smart for someone, but 
> i'm not able to find the correct solution on the web
>
> I would like to have a fixed structure of directory  
>
> DIR1 
> DIR2
> DIR3 
> ..
>
> I would like to copy a Folder TEST1 (already created with file and image 
> e.g. ) with inside a Doc.MD  and put inside DIR1
>
> should i avoid to change any index.rst and what is the correct 
> configuration for this scenario .
>
> After insert 
> \DIR1
>  \TEST1(Doc.MD) inside)
>
>
> thani would like to run make html  without add TEST1 manually in the 
> index.rst 
>
> What I should need is the correct file in the root 
> and then the correct fie in each DIR1 , DIR2  to obtain and discover new 
> folder with inside the new file doc.
>
> Thank you 
> Marco Longo 
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/e62791bf-6775-4ccc-933f-d3bfc5091205%40googlegroups.com.

[sphinx-users] Re: best wiki to produce documentation

[Peter Burdine]

Are you asking to go from Sphinx -> Wiki?  If so you can use the confluence 
builder: https://github.com/sphinx-contrib/confluencebuilder

Or are you asking to get documentation from a Wiki and then have Sphinx do 
something for it?

On Thursday, February 20, 2020 at 3:56:26 AM UTC-8, Renato Pontefice wrote:
>
> hi,
> I would use sphinx-doc to obtain documentation (sw documentation) 
> The doc. should be wrote from more people (the sw developer)
> then I could translate in HTML or PDF
> So, I need a wiki to collect this documentation.
> I'm wondering if sphinx-doc can accept just text files as input or also a 
> SQL file (e.g. the Tra wiki, store rst doc in a DB)
> If yes, can someone sudgest me a wiki to do that?
>
> TIA
> Renato
>

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/8b9cda0e-e0ff-4364-8c1a-d78c07717973%40googlegroups.com.

[sphinx-users] Re: automatically, the address is replaced with 'html#id1' like this.

[Peter Burdine]

You *could* make it do that, but then you would make making your own 
anchors for each section:

.. _1101:

1101


..raw:: html 
:file: _static/1101.html



On Tuesday, February 11, 2020 at 6:33:04 PM UTC-8, Orang Gendut Korea wrote:
>
> Hello~!
>
> I'm migrating our local html file to sphinx...
>
> but the address is automatically replaced with #id1 , #id2, #id3  
>
> I don't know how to make it ...
>
> My problem
> example.com/test.html#id1
> example.com/test.html#id2
>
> My expectation
> example.com/test.html#1101
> example.com/test.html#1102
>
> I attached my rst file.
>
> [image: Capture.JPG]
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/a5a7bfa1-8b76-461b-8ad0-5da1a859ac74%40googlegroups.com.

[sphinx-users] Re: parse generated output from program

[Peter Burdine]

Make your own directive that runs your command.  You can probably use the 
programoutput extension code as a reference for how to make the directive.  
Then use the nested_parse_with_titles function:
from docutils import nodes
from docutils.statemachine import ViewList 

def run(self):
new_content = command.output
node = nodes.Element()
node.document = self.state.document
env = self.state.document.settings.env
sphinx.util.nodes.nested_parse_with_titles(self.state, 
   ViewList(new_content.
splitlines(), source=env.docname),
   node)
return node.children

--Peter

On Friday, January 17, 2020 at 1:56:38 AM UTC-8, DexterMagnific wrote:
>
> Dear all,
>
> I have some script that generates ReST content. I'd like to call this 
> script from inside the rst document:
>
> blah blah blah
>
> .. execute-program:: generate-content.py myfile.bin
>
> I know there is sphinxcontrib.programoutput, but this extension inserts 
> the output of the program. What i'd like to is that this output be 
> interpreted by the parser as a rest content.
>
> Do you have any idea on how to achieve this ?
>
> Thanks
>

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/533e8dd9-23c4-4844-aa28-8b3e94743139%40googlegroups.com.

[sphinx-users] Re: Documenting + consolidating multiple repos/directories into one searchable html output

[Peter Burdine]

They way we have done this in the past is to link (eg ln -s) all of the 
other repos into your source directory, then perform a build.

On Friday, October 4, 2019 at 2:57:07 PM UTC-7, Nicholas Yue wrote:
>
> Hi,
>
>   I have success documenting individual repo/directory
>
>   However, I would like to document a collection of related (git) 
> repositories python source code into on html outputdir.
>
>   Is that possible ? What is the recommended approach ?
>
>   I have had a look at sphinx-multibuild with multple "-i" options but the 
> generated HTML files only documents the last input directory.
>
> Cheers
>

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/5ae984a1-13b2-4ed8-8e72-64d83f43726b%40googlegroups.com.

Re: [sphinx-users] Re: Prevent documentation of infinite loops

[Peter Burdine]

Is your code protected by:

if __name__ == "__main__":
main()

If you dont have something like this, your code will be executed when the
files are exec'd to get the doc strings.

On Tue, Jul 30, 2019, 13:34 Peter Burdine  wrote:

> I don't believe Sphinx (by default) uses while loops.  Are you writing
> your own extension or using an installed extension?  We've had an issue
> like this in the past when using jinja.  Is that what you are talking about?
>
> On Monday, July 22, 2019 at 1:57:46 AM UTC-7, József Pohl wrote:
>>
>> Hi,
>>
>> My sphinx generator worked fine until I added an infinite loop to the
>> code. It should only exit on key press which makes sphinx run in an
>> infinite loop and it can be terminated only by killing the process.
>> Can you please advise a workaround for this? Is there an option to tell
>> sphinx that it should ignore discovering "while true" loops?
>>
>> Regards
>> Joe
>>
>> --
> You received this message because you are subscribed to a topic in the
> Google Groups "sphinx-users" group.
> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/sphinx-users/DYikQD3IO5A/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to
> sphinx-users+unsubscr...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/sphinx-users/df1fe68e-83cf-411d-9cf9-c5faa5da5a51%40googlegroups.com
> <https://groups.google.com/d/msgid/sphinx-users/df1fe68e-83cf-411d-9cf9-c5faa5da5a51%40googlegroups.com?utm_medium=email_source=footer>
> .
>

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/CAGmaT9mBdWC%3DcN-DpJ2gHzpJGi2WWR_3tqx1VALdXB7Ba%2BsP2g%40mail.gmail.com.

[sphinx-users] Re: Prevent documentation of infinite loops

[Peter Burdine]

I don't believe Sphinx (by default) uses while loops.  Are you writing your 
own extension or using an installed extension?  We've had an issue like 
this in the past when using jinja.  Is that what you are talking about?

On Monday, July 22, 2019 at 1:57:46 AM UTC-7, József Pohl wrote:
>
> Hi,
>
> My sphinx generator worked fine until I added an infinite loop to the 
> code. It should only exit on key press which makes sphinx run in an 
> infinite loop and it can be terminated only by killing the process.
> Can you please advise a workaround for this? Is there an option to tell 
> sphinx that it should ignore discovering "while true" loops?
>
> Regards
> Joe
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/df1fe68e-83cf-411d-9cf9-c5faa5da5a51%40googlegroups.com.

[sphinx-users] Re: Sphinx Active Directory / LDAP integration

[Peter Burdine]

Sphinx isn't a web server or any other server.  If you are going use it to 
generate a knowledge base, then you are going to need another tool (web 
server, network share, confluence, etc) that is responsible for the 
protection you are looking for.  Someone may be able to offer some 
recommendations/suggestions if you provided a bit more detail.  What output 
format are you looking at, eg html or pdf?  If your team uses Atlassian 
tools there is a confluence builder extension you might want to look at.  
You will probably also need a CI tool to generate new documentation when 
some makes a change (TeamCity/Jenkins/etc) as well as source control 
(SVN/git/etc).  Your source control tool may also be able to restrict RW 
permissions.

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To post to this group, send email to sphinx-users@googlegroups.com.
Visit this group at https://groups.google.com/group/sphinx-users.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/cb5d1577-962b-4b0c-a80a-f21e3bf4189d%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[sphinx-users] Re: Advice on finding a Sphinx consultant?

[Peter Burdine]

Doh!  I meant *lack* of responses.

On Monday, May 13, 2019 at 7:23:57 AM UTC-7, Peter Burdine wrote:
>
> I believe at one point in time they were actively discouraging advertising 
> of services on this group, even when related, which is probably one of the 
> reasons for the lake of responses.  
>
> On Friday, January 29, 2016 at 1:35:45 PM UTC-8, Chris Chang wrote:
>>
>> We're looking to revamp our documentation and really like a lot of 
>> features that come with Sphinx. Unfortunately we don't have much experience 
>> with it, so we're looking to see if there are any Sphinx consultants that 
>> may be able to help us out.
>>
>> Thanks in advance!
>>
>

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To post to this group, send email to sphinx-users@googlegroups.com.
Visit this group at https://groups.google.com/group/sphinx-users.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/166900d7-d95c-4411-8871-f934a2dfeb66%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[sphinx-users] Re: Advice on finding a Sphinx consultant?

[Peter Burdine]

I believe at one point in time they were actively discouraging advertising 
of services on this group, even when related, which is probably one of the 
reasons for the lake of responses.  

On Friday, January 29, 2016 at 1:35:45 PM UTC-8, Chris Chang wrote:
>
> We're looking to revamp our documentation and really like a lot of 
> features that come with Sphinx. Unfortunately we don't have much experience 
> with it, so we're looking to see if there are any Sphinx consultants that 
> may be able to help us out.
>
> Thanks in advance!
>

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to sphinx-users+unsubscr...@googlegroups.com.
To post to this group, send email to sphinx-users@googlegroups.com.
Visit this group at https://groups.google.com/group/sphinx-users.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/826a08cf-2e25-46ad-9e60-434f4b369897%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[sphinx-users] Re: :doc: in a custom directive

[Peter Burdine]

Hmm, I don't use self.state.nested_parse, this is how I've done it:

sphinx.util.nodes.nested_parse_with_titles(self.state, 
   ViewList(new_content.
splitlines(), source=docname),
   node) 
return node.children
Where new_content is the reST code to parse, and node is the current node.


On Monday, January 28, 2019 at 9:38:50 AM UTC-8, Matthew Woehlke wrote:
>
> On 23/01/2019 10.27, Maxime Adam wrote: 
> > With that's said I'm willing to do this following directive 
> > 
> > class MarkAsDeprecated(Directive): 
> > 
> > def run(self): 
> > 
> > txt = "Blablabla moved to :doc:{0}".format(self.arguments[0]) 
> > paragraph_node = nodes.paragraph(text=txt) 
> > 
> > return [paragraph_node] 
> > 
> > But :doc: is not render. I think I should insert a pending_xref (not 
> > sure it's the correct one but it's seems to be) node but I really 
> > don't know how to do it. 
>
> In such cases, I find it is often helpful to look at how the role in 
> question is implemented. 
>
> However, there is another option which you may find easier, especially 
> as you need to generate several nodes for your directive's body: use 
> self.state.nested_parse to convert your reST source to nodes. 
>
> -- 
> Matthew 
>

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

[sphinx-users] Re: Get full documentation tree

[Peter Burdine]

See:
https://groups.google.com/forum/#!msg/sphinx-users/0UW05Inwfac/X8bCZmlLBwAJ
This is what I did a few years back.  The builders are inconstant when they 
create events and I haven't been able to figure out how to make it work 
either.

I have an extension that followed the todo example, which works great when 
> the output is latex, but for HTML it doesn't work right.  The reason for 
> this seems to be that we are using Sphinx for a modular documentation 
> project so not all of the files will be included in the output.  When using 
> the latex builder, we get a single doctree when the 'doctree-resolved' 
> event is called.   When using the HTML builder, it gets called once for 
> every input file.  Since I want to only include found items that are in the 
> final document, I found I can't trust the information I have when 
> 'doctree-resolved' is emitted since the final document structure isn't 
> complete.  The only time I have found that I can trust that the document 
> has been assembled is when the 'env-updated' event is emitted, and then I 
> can browse the document tree like:
>
> def env_updated(app, env):
> relations = env.collect_relations()
> included_docs = []
> updated_docs = []
> # Each relation is a list in the following order [parent, prev_doc, 
> next_doc]
> cur_doc = env.config.master_doc
> while cur_doc:
> included_docs.append(cur_doc)
> doctree = env.get_doctree(cur_doc)
> cur_doc = relations[cur_doc][2]
>
> This gives me a nice list of the documents in the order that they will be 
> in.  I can even find all of the elements I want using:
>
> for docname in included_docs:
> doctree = env.get_doctree(docname)
> for table in doctree.traverse(my_node_type):
> updated_docs.append(docname)
> # Add rows to the table here...
> return updated_docs
>
>
> At the end of the handling the 'env-updated' event, I return a list of 
> documents I've modified (in my case, I appended rows to an existing table), 
> then I return the list of docnames I've modified.  However, none of the 
> rows I've added to the table will show up in the final output.  The code to 
> modify the table is good, it worked just fine in the 'doctree-resolved' 
> event handler, so I don't think that is the issue.  Is there something I 
> need to do other the returning the list of docnames from the 'env-updated' 
> event handler to make these changes stick?
>


On Monday, February 4, 2019 at 3:26:25 AM UTC-8, balv...@boxfish.studio 
wrote:
>
> Hi Michael, thank you very much for your reply,
>
> I am already using wkhtmltopdf to build PDF from HTMLs. Also, I already 
> tried the singlehtml and indeed works but the problem is that it increases 
> so much the build time that it makes kind of impossible to work locally to 
> test. Using singlehtml to build the PDFs means building 1 time for the 
> documentation and n-times for each desired PDF, which can lead to building 
> time of hours. That is why I would like to avoid rebuilding the 
> documentation, simply converting the current build to PDF reduces so much 
> the time, but as mentioned, getting the *full* (infinite depth) tree from 
> the built html seems tricky. 
>
> On Saturday, February 2, 2019 at 1:02:54 PM UTC+1, Michael Gielda wrote:
>>
>> Have you looked at WeasyPrint on a single html build? Don't know how well 
>> it works for your use case but that's what I would try first. It's in 
>> Python (yay), and a direct HTML to PDF converter, implementing the CSS Page 
>> spec (for stuff like headers and footers).
>>
>> Best regards 
>> Michael 
>>
>

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

[sphinx-users] Re: explain "updating environment" please

[Peter Burdine]

It may depend on what extensions you have running.  Those may flag ALL 
files as being changed so the extension can reprocess them.

--Peter

On Wednesday, October 3, 2018 at 8:22:02 AM UTC-7, ryanwist wrote:
>
> Hi Paul,
>
> Thanks for the reply -- good to have pointers on where to look.  I can 
> report:
>
> No -E on build (using either make.bat or sphinx-build directly).
> The pickle is being built.
> All files are local - no sleight of hand with the cloud.
> conf.py did have a number of extensions, but removing them all had no 
> effect.
>
> I did determine that reducing my file set by using "exclude_patterns" in 
> conf.py does *lower *the number of "changed" files -- but as previous, 
> after all the above are tried, I still get a fixed number of changed files 
> on build, even when nothing in fact has changed.
>
> Further inquiry not needed; I appreciate the help to this point.  I was 
> hoping that reducing/eliminating the "changed" total would speed my build 
> time, but after the testing I've done for this I'm fairly certain that the 
> doc set size (too big!) is the real issue there.
>
>
>

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

[sphinx-users] Re: How to install on machine with no internet access

[Peter Burdine]

On an internet connected machine run:
pip download --process-dependency-links --disable-pip-version-check -d 
sphinx_install sphinx

Where sphinx_install is the directory where you want to store the files you 
are downloading.  Then transfer that directory to a non-internet connected 
machines and run:
pip install --upgrade --no-index --find-links=sphinx_install sphinx

--Peter


On Monday, March 19, 2018 at 3:43:09 PM UTC-7, Hanz Husseiner wrote:
>
> Hello:
>did you manage to install sphinx on your no internet machine?
>
> I am running through the same issue. we are trying to install sphinx on 
> our dev server. managed to install python, pip and both working fine but 
> was unable to install sphinx.. Thank you for your help.
>
>
> On Friday, September 28, 2012 at 9:09:30 AM UTC-4, Tawez wrote:
>>
>> On Tuesday, September 25, 2012 3:25:17 PM UTC+2, Alexander Gray II wrote:
>>
>>> Hi,
>>> We have machines that do not have internet access and we would like to 
>>> install Sphinx on them.
>>> I downloaded the egg and used the easy-install utility to install it.  
>>> It fails when it tries to download the dependencies from the internet.
>>>
>>
>> Is there an easy way to install this on a machine that does not have 
>>> internet access?
>>> Or is there a list of all the dependencies that Sphinx has?
>>> Thanks!
>>>
>>
>> Hi,
>>
>> Take a look at easy_install documentation.
>>
>> http://packages.python.org/distribute/easy_install.html#installing-on-un-networked-machines
>>
>> Download all the dependencies on networked machine:
>>
>> easy_install -zmaxd /where/store/eggs Sphinx
>>
>>
>> Then copy all the eggs to un-networked machine and run:
>>
>> easy_install -H None -f /where/are/eggs Sphinx
>>
>>
>> HINT: Copy eggs to folder on un-networked machine, go to this folder and 
>> run:
>>
>> easy_install -H None -f . Sphinx
>>
>>  
>> If You need list of dependencies, at the moment of writing it is:
>> - sphinx
>> - docutils
>> - jinja2
>> - pygments
>>
>>
>> --
>> regards
>> Tawez
>>
>>

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

[sphinx-users] Re: Newbie: can I combine dynamic data to one page?

[Peter Burdine]

A few things:
1) You may want to consider another jinja extension to sphinx: 
https://pypi.python.org/pypi/sphinx-jinja.  We use YAML as the datasource, 
though it could be anything maps to Python lists/dicts (json, xml, etc).  
You can then either reference the a file with the jinja template, or you 
can embed the jinja code in your .rst files.  We have found it is easiest 
to make list tables for this.  You can use 
{% if loop.first %}
to setup your table headers.


2) The builder controls the output formatting not the reST input (unless 
you use tablularcolumns for LaTeX, but that is another story).  Have you 
tried: 
https://stackoverflow.com/questions/23462494/how-to-add-a-custom-css-file-to-sphinx


On Wednesday, March 28, 2018 at 12:45:44 AM UTC-7, Jan wrote:
>
> I'm trying to understand sphinx, and I'm thoroughly not understanding how 
> to implement even some basic concepts. I've created a sphinx project linked 
> to my readthedocs account. Everything works to generate my basic index.rst 
> file in read the docs. I'm trying to follow the ideas of adding dynamic 
> input to a specific page within my project, as mentioned here: 
> http://ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/
>
> My objective is to setup my sphinx project so that whenever a specific 
> text file changes in my /docs folder, it updates my ReadTheDocs content 
> dynamically/automatically.
>
> My /docs folder has these key elements:
>
> parsethisfile.txt
> conf.py
> index.rst
> Database.rst
> ...
>
> In my conf.py I've added some python which parses a txt file, and then 
> creates references to the object:
>
> def rstjinja(app, docname, source):
> """
> Render our pages as a jinja template for fancy templating goodness.
> """
> # Make sure we're outputting HTML
> if app.builder.format != 'html':
> return
> src = source[0]
> rendered = app.builder.templates.render_string(
> src, app.config.html_context
> )
> source[0] = rendered
>
> def setup(app):
> app.connect("source-read", rstjinja)
>
> html_context = {
> #'outputschema': schema_list_out
> }
>
> The "schema_list_out" is a list (or I could make a dictionary) which 
> contains elements for a database schema, such as table names, comments, 
> column names and column parameters.
>
> If I wanted to generate dynamic ReadTheDocs pages, I've successfully been 
> able to add some variables to my Database.rst file like this:
> {% for schema_item in outputschema %}
> **Schema Name: {{ schema_item["name"] }}**
> {% endfor %}
> and sphinx correctly creates a Database.html file that shows this:
>
> Schema Name: buildings
>
> More importantly, I'm trying to create nice looking tables for the items 
> in my "schema_list_out" list. The only way I've been able to do that is 
> using the python tabulate module (in my conf.py), where I generate the 
> table within python, output as rst, and save it as a list element object 
> within my "schema_list_out". If I use the right control structure in my 
> rst, I generate a nice looking table in rst format that looks correct in my 
> sphinx generated output:
>
>
> 
> But the problem here is I have no way of controlling how this looks inside 
> the rst file because it's RST, and I can't add HTML, css or anything else 
> to control how the table looks (like table width, color etc). reST markup 
> doesn't seem to offer enough control over a table.
> How do I create dynamically created tables which can be formatted nicely, 
> in RST? If I could create the tables easily in my Database.html, I'd do 
> that, but it's not a template, it's generated by sphinx from my 
> Database.rst. I can't figure out how to create my Database.html myself, 
> with the jinja control structures inside of it. How do do that?
>
>
>
>
>

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

[sphinx-users] Re: How to align LaTeX PDF tables left again

[Peter Burdine]

You have to use the tabularcolumns directive, which can take a ton of latex 
commands for formatting of columns, such as:

.. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 0.3\linewidth-2\tabcolsep}
|>{\RaggedRight}p{\dimexpr 0.45\linewidth-2\tabcolsep}
|>{\RaggedRight}p{\dimexpr 0.25\linewidth-2\tabcolsep}|


This will create columns that are 30%, 45%, 25%, all left aligned with 
vertical lines between cells.

--Peter

On Wednesday, January 10, 2018 at 2:17:59 PM UTC-8, Erin Kelly wrote:
>
> Apparently in 1.6.1 the default table alignment changed from left to 
> center. I want all my tables to align left. 
>
> The change documentation says I can use Docutils :align: option but that 
> only works if I'm using a .. table:: tag
> I'm using this style of tables: 
> +++---+
> | Header 1   | Header 2   | Header 3  |
> +++===+
> | body row 1 | column 2   | column 3  |
> +++---+
>
> I tried throwing the table tag above this kind of table but it didn't 
> understand that. 
>
> Is there something I can put in the latex preamble to reset the default to 
> align left? 
>

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

[sphinx-users] Re: Help need for latex output

[Peter Burdine]

Also, see this older discussion: "Actual, working example of latex-pdf 
cover page?" 
https://groups.google.com/forum/#!topic/sphinx-users/S_ip2b-lrRs

It has some other examples found on github and some additional discussion.

--Peter

On Friday, December 29, 2017 at 6:04:06 AM UTC-8, Rene Dworschak wrote:
>
> Hello
>
> i need some help with the latex output from sphinx - my old conf files 
> aren't working.
>
> First i am using Python3.6 / Sphinx v1.5.6 with Jupyter Notebook Tools for 
> Sphinx to get html/pdf output from my notebooks. So far it works.
> Long time ago i have used http://jterrace.github.io/sphinxtr/ for my RST 
> documentation. (Python 2 + old sphinx)
>
> The old sphinxtr template got a nice titlepage modification ..but now i 
> did not get it to work.
>
> so my questions are for Sphinx v1.5.6. What i the best way to get
>
> * custom titlepage (in a separate single file which can be included)
> * custom page behind the titlepage (in a separate single file which can 
> be included)
> * image in the \fancyhead
> * copy additional files into tex build dir?  
>
> Proposals welcome
>
> regards René
>
>
>
>
>
>
>
>

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

[sphinx-users] Re: Help need for latex output

[Peter Burdine]

I haven't used the Jypyter notebook extension, but I would assume it is the 
same process.  You need to include a LaTeX preamble that overwrites various 
macros predefined by Sphinx.  I haven't updated to 1.5 yet (still on 1.4).  

Update your conf.py to specify a preamble:
PREAMBLE = string.Template(open(
os.path.join(os.path.abspath('.'),'preamble.tex')
).read())
latex_elements = {
...
'preabmle': PREAMBLE, 
...
}

Then the title page (and all the front matter) is made by the \maketitle 
macro, so you will need to redefine it in your preamble, eg:
\renewcommand{\maketitle}{%
  \begin{titlepage}%
\pagenumbering{roman}
\thispagestyle{titlepage}


\newpage  % Make as many pages in the front matter as you want
% Second page contents go here
  }%
}


As for the custom logo, you can setup the headers with something like this::
\fancypagestyle{normal}{
\fancyhead[L]{\sphinxlogo
  \vfill}
}


You set the path to the logo in your conf.py:
latex_logo = 'some_relative_path/image.png'

Its been a long time since I set this up, so I may be missing a few steps.  
You need to become at least a beginner in LaTeX to make this work.  It took 
me quite a few days to make it work right the first time I did that, and 
that was a year and a half ago, so my memory is a bit fuzzy.

Good luck!

--Peter


On Friday, December 29, 2017 at 6:04:06 AM UTC-8, Rene Dworschak wrote:
>
> Hello
>
> i need some help with the latex output from sphinx - my old conf files 
> aren't working.
>
> First i am using Python3.6 / Sphinx v1.5.6 with Jupyter Notebook Tools for 
> Sphinx to get html/pdf output from my notebooks. So far it works.
> Long time ago i have used http://jterrace.github.io/sphinxtr/ for my RST 
> documentation. (Python 2 + old sphinx)
>
> The old sphinxtr template got a nice titlepage modification ..but now i 
> did not get it to work.
>
> so my questions are for Sphinx v1.5.6. What i the best way to get
>
> * custom titlepage (in a separate single file which can be included)
> * custom page behind the titlepage (in a separate single file which can 
> be included)
> * image in the \fancyhead
> * copy additional files into tex build dir?  
>
> Proposals welcome
>
> regards René
>
>
>
>
>
>
>
>

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

[sphinx-users] Re: Tweaking automatic section numbering?

[Peter Burdine]

What is your desired output?  We do all of this in Latex, it requires 
adding a bit of LaTeX in your preamble.



On Friday, October 13, 2017 at 7:29:52 AM UTC-7, Matthew Woehlke wrote:
>
> I filed this also as an RFE¹ but haven't gotten any feedback so far; 
> trying here instead. 
>
> What would be the most plausible way to generate automatic section 
> numbers with the following requirements: 
>
> - Not all sections are numbered. Multiple blocks of sections *are* 
> numbered, with the numbering restarting in between. (It seems Sphinx 
> already handles this case just fine by using multiple toctree 
> directives, so that's good.) 
>
> - Section numbers need to be preceded by other text, e.g. "Appendix". 
>
> - Different blocks of numbered sections need to use different numbering 
> schemes. In particular, the aforementioned appendices should use Roman 
> numerals (I, II, etc.). 
>
> Is there any way to accomplish this that doesn't require either a) 
> modifying the guts of Sphinx itself, or b) duplicating lots and lots of 
> low-level Sphinx code? (I initially tried to replicate how Sphinx 
> auto-numbering works, but it looked like I was going to have to 
> replicate significant parts of Sphinx for that approach to be feasible.) 
>
> If the right answer is to change Sphinx, what would be the recommended 
> way to implement these features such that they can be incorporated into 
> upstream? (And, on a related note, is there a way in Python, or even 
> better, already in Sphinx itself, to translate integers to Kanji 
> numbers, Hebrew numbers, etc.?) 
>
> (¹ See also https://github.com/sphinx-doc/sphinx/issues/4133.) 
>
> -- 
> Matthew 
>
>

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

[sphinx-users] Re: How to use substitution in code-block with code highlight

[Peter Burdine]

Or you can use another directive do the replace first, then process the 
code block.  We use the Jinja extension to do this on a regular basis.

Note that we are still using Sphinx 1.4.x and highlighting only works for 
HTML, it does not highlight in PDF output.  I do not know if it has been 
fixed in later versions or if this matters to you.

--Peter

On Tuesday, October 3, 2017 at 5:37:10 PM UTC-7, Kengo TODA wrote:
>
> Hello sphinx-users,
>
>
> Thanks for your support to make documentation easy.
> Could you tell me how I can use substitution in code-block with code 
> highlight?
>
>
> *# background*
> I'm making a web page which includes sample build script:
> http://spotbugs.readthedocs.io/en/latest/migration.html
>
> This page includes version of the latest release of our product,
> and I need to update .rst file manually to realize keeping the latest 
> version in this page.
> Let me ask how I can eliminate manual tasks like this.
>
> I've found that I can use substitution and sphinx.ext.extlinks help me.
> It works if version exists in text or hyperlink. But in case of code-block,
> I cannot use substitution.
>
> *# incomplete solution*
> I found the solution using parsed-literal block, but it doesn't support 
> code highlight
> so look & feel are really bad.
> - https://stackoverflow.com/a/12644533/814928
>
> *# known workaround*
> Maybe it is possible to:
> 1. write code snippet into template file with |release| and/or |version|,
> 2. generate replaced text from these template,
> 3. write replaced text into temporal file, and
> 4. use literalinclude directive (which supports code highlight) to include 
> replaced text
>
> I wish we have better solution which can simplify document generation.
>
>
> Thanks in advance,
> Kengo TODA
>

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

[sphinx-users] Re: Using variables inside code block and httpdomain directives

[Peter Burdine]

A code block isn't parsed.  If you want Sphinx to process it, you need to 
use a parsed-literal.  This also comes with all the downsides of being 
parsed, escaping, markup, etc.

I don't know about the http directive.

Depending on how much you need to do, you may want to look at the jinja 
extension.  The contents of jinja blocks including subdirectives (like 
code-block) are parsed by jinja first, then Sphinx.

--Peter

On Wednesday, September 13, 2017 at 1:35:34 AM UTC-7, Adam Szmyd wrote:
>
> Is it possible to use some kind of variable mechanism in code blocks?
>
> I.e. i have such line in `conf.py`:
>
> my_config_value = 42
> rst_epilog = '.. |my_conf_val| replace:: %d' % my_config_value
>
>
> And when i use it in some regular text like so:
>
> My config value is |my_conf_val|!
>
>
>
> Sphinx nicely replace the var and output as follows:
>
> My config value is 42!
>>
>
> But when i try the same using code block:
>
> .. code-block:: javascript
>
>  // |my_conf_val|
>
>
> I get unreplaced *|my_conf_val|* string in the output.
>
> Is it possible to achieve something similar (variables) inside code block?
> Not sure if its related but it seems that other directives also does not 
> handle this properly, i.e. `http` directive from `sphinxcontrib.httpdomain` 
> package:
>
> .. http:get:: |my_conf_va||/users
>
>
> Is also not replacing.
>
>

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

Re: [sphinx-users] Re: master_doc variable doesn't influence html/latex builders

[Peter Burdine]

Creating the links and scripting it is much easier with a Cygwin env
because it has all of the utilities built in (find, make, etc).  If we had
to create our management scripts using ps/bat, I would probably just give
up.

To expand on what we do, we actually create a file with a listing of all
the link source/target pairs (that gets checked into SVN), then have a
Python script to looks for all the links in the project and deletes the
incorrect ones and makes the correct ones, then adds them to the SVN ignore
list.  This is a pain on Windows because it doesn't understand relative
links, it is actually an absolute link, so depending on where people check
their SVN repo out, their links are different.  Also, SVN on windows
doesn't understand links (because windows...), hence the bit about adding
them to the ignore list and not checking them in.

This approach solves two of our problems:
1) Getting content from outside of the source directory
2) The ability to include a file more than once.   We are also using the
jinja extension and a modified toctree directive so the files can get
rendered in a different context depending on the path to the file.

On Fri, Sep 1, 2017 at 7:49 AM, Dessus Ph. <pdes...@gmail.com> wrote:

> thx Peter,
> 1. Sphinx can run pretty well on Windows, AFAIK. Follow the install
> instructions.
> 2. Good idea; a bit tricky, but I'll try it. No more elegant solution ? ;-)
> best,
> ph
>
>
> Le vendredi 1 septembre 2017 16:39:35 UTC+2, Peter Burdine a écrit :
>>
>> We do the same thing here, produce a bunch of documents from a common set
>> of files.  We are on Windows, which makes it a little difficult, so we run
>> Sphinx from a Cygwin environment.  Then we create individual document
>> directories.  To get the common content we create links from within Cygwin
>> to make the common content appear under each document directory.  This way
>> each document can be built the way we want it.
>>
>> --Peter
>>
>> On Friday, September 1, 2017 at 5:15:49 AM UTC-7, Dessus Ph. wrote:
>>>
>>> dear all,
>>>
>>> I'm currently working on a large set of sphinx files of which I want to
>>> produce different subsets with different outputs (mainly HTML/PDF).
>>> So I've written different index files to be compiled.
>>>
>>> My problem is that putting the index file name in the master_doc
>>> variable *only* affects, AFAIK, the singlehtml output, both html and
>>> latex make commands don't use the master_doc specified index (they compile
>>> *indifferently* all the files in the folder whatever the index name is).
>>>
>>> I'm aware that intersphinx would fix this problem but with a too
>>> complicated folder structure (it's more convenient to me to have all the
>>> files in a same folder).
>>>
>>> Any ideas on how to specify the compilation of a given set of files as
>>> an index?
>>>
>>> best and thx!
>>> philippe
>>>
>> --
> You received this message because you are subscribed to a topic in the
> Google Groups "sphinx-users" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/
> topic/sphinx-users/enM8GeHc680/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to
> sphinx-users+unsubscr...@googlegroups.com.
> To post to this group, send email to sphinx-users@googlegroups.com.
> Visit this group at https://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/d/optout.
>

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

[sphinx-users] Re: Set background color for block of parsed text for pdflatex output

[Peter Burdine]

For PDF output, the "easiest" way is add a latex preamble that redefines 
the style.  The style names sometimes change from version to version (eg, 
I'm still on 1.4.4, I know they are different in 1.5).

I store the premble in a .tex file outside of the conf.py, like so:
PREAMBLE = string.Template(open(
os.path.join(os.path.abspath('.'),
'latex_templates/preamble.tex')
).read())
latex_elements = {
#Other contents here
'preamble': PREAMBLE
}

Eg, I did the following to make all the admonitions to be upper case and 
centered:
\renewenvironment{notice}[2]{
  \def\py@noticetype{#1}
  \csname py@noticestart@#1\endcsname
  % Make the admonition type be upper case and on its own line
  \begin{center}\strong{\MakeUppercase{#2}} \\\end{center}
}{\csname py@noticeend@\py@noticetype\endcsname}


Unfortunately, this involves learning latex and trying to figure out how 
the Sphinx styles work.

--Peter

On Saturday, August 19, 2017 at 7:38:13 AM UTC-7, Imre Deak wrote:
>
> Hi,
>
> I'd like to set the background color and font type for a block of text 
> that would be rendered correctly both in html and pdflatex outputs. What I 
> tried so far without success:
>
> - .. parsed-literal directive
>   This renders a gray background color only in the html output, the 
> pdflatex output renders the text on a white background which can't be 
> changed. Also I'd like to avoid having line breaks where the .rst version 
> has a line break, instead I'd like the lines to be automatically reflowed 
> based on available width as for normal text. (I know I can make long lines 
> break automatically, but this is not what I want.)
>
> - .. note/warning etc. directives
>   These add the "Note", "Warning" etc. captions which I don't want.
>
> - .. container:: class
>   This allows for a custom html syling by adding a .css style for "class", 
> but the pdflatex output won't have any markup that I could use (redefine) 
> for a custom style. .. role's emit a \DUrole markup which I think could be 
> used for custom styles, but I want something for a whole block of text, 
> that is for an rst directive.
>
> Is there some way (using the above or some other approach) to do what I 
> want?
>
> I believe it could be done with a sphinx extension, if so could someone 
> provide a sketch for this to get me started?
>
> Thanks.
>

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

[sphinx-users] Modifying a document in the 'env-updated' event

[Peter Burdine]

I have an extension that followed the todo example, which works great when 
the output is latex, but for HTML it doesn't work right.  The reason for 
this seems to be that we are using Sphinx for a modular documentation 
project so not all of the files will be included in the output.  When using 
the latex builder, we get a single doctree when the 'doctree-resolved' 
event is called.   When using the HTML builder, it gets called once for 
every input file.  Since I want to only include found items that are in the 
final document, I found I can't trust the information I have when 
'doctree-resolved' is emitted since the final document structure isn't 
complete.  The only time I have found that I can trust that the document 
has been assembled is when the 'env-updated' event is emitted, and then I 
can browse the document tree like:


def env_updated(app, env):
relations = env.collect_relations()
included_docs = []
updated_docs = []
# Each relation is a list in the following order [parent, prev_doc, 
next_doc]
cur_doc = env.config.master_doc
while cur_doc:
included_docs.append(cur_doc)
doctree = env.get_doctree(cur_doc)
cur_doc = relations[cur_doc][2]

This gives me a nice list of the documents in the order that they will be 
in.  I can even find all of the elements I want using:

for docname in included_docs:
doctree = env.get_doctree(docname)
for table in doctree.traverse(my_node_type):
updated_docs.append(docname)
# Add rows to the table here...
return updated_docs

At the end of the handling the 'env-updated' event, I return a list of 
documents I've modified (in my case, I appended rows to an existing table), 
then I return the list of docnames I've modified.  However, none of the 
rows I've added to the table will show up in the final output.  The code to 
modify the table is good, it worked just fine in the 'doctree-resolved' 
event handler, so I don't think that is the issue.  Is there something I 
need to do other the returning the list of docnames from the 'env-updated' 
event handler to make these changes stick?

Thanks,
Peter

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

[sphinx-users] Re: Specifically wrapped function & automodule

[Peter Burdine]

IIRC the current versions of Sphinx/Autodoc don't work well with decorated 
functions.  Try adding the actual function signature as the first line in 
the doc string.  Eg:

@Operation.register('foo')
def func(arg):
 """func(arg)
 
Documentation of decorated function"""
pass  




On Friday, June 16, 2017 at 4:35:39 PM UTC-7, Maciek Olko wrote:
>
> Hi all,
> consider the snippet [1] and autodoc-automodule-decorated-docstrings.rst:
>
> autodoc-automodule-decorated-docstrings module
> ==
>
> .. automodule:: autodoc-automodule-decorated-docstrings
> :members:
> :undoc-members:
> :show-inheritance:
>
> Decorated function func() is missing from generated documentation. Do you 
> know why it is omitted? It is IMO proper member of the module.
>
> [1] https://gist.github.com/m-aciek/e45c912a1b4720f843635dfba3a50ad1
>
> Regards,
> Maciej
>

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

Re: [sphinx-users] cross referencing autonumbered list items

[Peter Burdine]

Since this is reST, you need to be careful with line numbers.  To make 
autonumbered sub-items, you just need use the normal auto number (#.), but 
have blank lines and indentations around each level change, eg:
#. An Item

  #. A Subitem

#. A subsub item
#. Another subsub item
  
  #. Another sub item


Each time you indent to a new level, it gives you the next level of sub 
items.

As for referring to a specific one, I don't know of an obvious/easy one.  A 
guess of a non-obvious one would be to declare a reST replacement node that 
defines a new anchor, then include that inline with the item you want (like 
trying to declare an inline image), then try to link to it (you can try 
:numref: or :any:).  But I don't think that will give you the item number.  
Also, it maydepend on which version of Sphinx you are using.  1.4.x doesn't 
have a method to get the section number for headers, I think that was added 
in 1.5.x.  I'm not sure that extends to numbered lists as well.

--Peter

On Sunday, June 18, 2017 at 11:35:13 PM UTC-7, kworm wrote:
>
> Hi Daniele,
>
> Thanks for the answer. You seem to indicate that it was in answer to my 
> second question, which was how to make sub-numbered list. I fail to see how 
> to do that though. The link you posted explains how I can create a list 
> like this
> 1. An item
>   1. A sub item
>  1. A sub sub item
>  2. Another sub sub item
>   2. Another sub item
> 2. Another item
>
> but not how to get sub-numbers.
>
> It did however, partially explain my other question which is how to link 
> to a list item. I.e. I can do so by putting the label at the right 
> indentation. It still does not include the number though which is what I 
> would like.
>
> Thanks
>
>
>
> On Thursday, 15 June 2017 17:42:56 UTC+10, daniele wrote:
>>
>> 2017-06-15 4:41 GMT+02:00 kworm : 
>> > A second question is whether it is possible to create sub-numbered 
>> lists. 
>> > Something that renders like this: 
>>
>>
>> stackoverflow.com/questions/34450064/how-to-make-nested-lists-with-automatic-numbering-in-sphinx
>>  
>>
>> regards 
>>
>> -- 
>>
>> Daniele 
>>
>> www.fugamatematica.blogspot.com 
>>
>> giusto! 
>> nel verso 
>> forse è perché non guardiamo le cose 
>> Quando non ci capiamo, 
>>
>

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

[sphinx-users] Re: How to number admonitions?

[Peter Burdine]

You can create serial numbers using 
env.new_serialno('your_string_here')

It should create a unique incrementing number for each string you give it.  
So if your wanted to create a special admonition, it would be: 
env.new_serialnl('special_admonition')
This would go in your directive's run method.

You may be able to monkey patch some of the admonitions adding this, or 
your could extend them and create your own directive.

On Monday, June 12, 2017 at 3:04:26 PM UTC-7, Augusto Teixeira wrote:
>
> Hey,
>
> I was wandering if it is possible to automatically number admonitions (or 
> to create a special admonition which is numbered). Something that works 
> well both when building for Latex and for HTML.
>
> Is this provided already or should I create an extension? In case it is 
> not very complicated I would be glad to implement it, but would appreciate 
> any hints on how to go about it.
>
> In fact I have asked this before in a question in Stack Overflow 
> ,
>  
> but it received no input...
>
> Best,
> Augusto
>

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

[sphinx-users] Re: How to namage big document . How to have a list of pages ?

[Peter Burdine]

The issue you are seeing is that you are linking to it via a hyperlink 
instead of including it in a toctree.  Thus it may work for the html 
builder, but if you output into latexpdf/epub/etc, your document will not 
work as expected.

If that is OK with you, then you can add the text as the first line of 
every rst file to suppress that warning:
:orphan:

Otherwise, you can change North_America.rst to look something like this:

*
 Presentation of Noth America
 *
 Norh_america is split in 2 contries.
 
 Canada
 == 
 .. toctree::

 content here

 USA
 ===
 The USA is split in 50 contries:


 .. toctree::
 
california
texas

This approach will remove the warnings and also work for builders other 
than html.  If you want to control the link text (not match the first 
heading in your linked file), then you can specify the titles:

 .. toctree::
 
california 
texas 



On Thursday, June 1, 2017 at 5:30:15 AM UTC-7, andre1925 wrote:
>
> Hello, 
>
>
> This my index.rst
>
>
> Welcome to world wide Documentation!
> ==
>
> .. toctree::
>:maxdepth: 2
>:caption: Contents:
>
>North_America
>Europa
>
> Then in North_America.rst, I have:
>
> *
> Presentation of Noth America
> *
> Norh_america is split in 2 contries.
>
> Canada
> ==
>
> USA
> ===
> The USA is split in 50 contries:
> * california  Hyperlink to california.html (that is built from 
> california.rst)
> * texas  Hyperlink to texa.html (that is built from texa.rst)
>
>  
>
> in fact for each countries I have 1 Mo of text. So to avoid a 
> North_America.rst/html page than is larger tahn 50 Mo, I use one contry = 
> one page. 
>
>
> This works, and user expeirence is OK. Nevertheless, I have 50 warnings: 
>
> d:\\texa.rst:: WARNING: document isn't included in any toctree
>
>
> As I access to the texas.html throught an hyperlink, I understand the 
> warning. Is is an elegant way to suppress it ?  Add in the doctree with an 
> hide mechanism ? 
>
>
> Is it possible to have an index of pages ? 
>
>
>

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

[sphinx-users] Re: Factoring toctree Stanzas?

[Peter Burdine]

I didn't make a test case, but we have found (with at least Sphinx 1.4.x) 
you can't always have the same file in two different tocrees go into the 
same document.  The behavior tends to be build specific.  For example if 
you included bar in both toctrees (without using :hidden:) and the first 
instance was section 3.3 you would get different results with html vs pdf:

html: bar would show up twice, but they both would be 3.3, even though the 
second instance is in the middle of section 4 or 5
pdf: The second instance would be silently dropped and not show up in the 
output at all

You may be running into something similar.

We work around this issue by creating symlinks to create 2nd instances of 
our source files so they can be included more than once if required.


On Friday, May 19, 2017 at 7:41:40 AM UTC-7, Horse Radish wrote:
>
> I have a use case where I want to use the same toctree in two different 
> contexts.  In one place I want it :hidden: (because it's just being used to 
> populate a sidebar), in another, I actually want the content visible on the 
> page.   I was hoping to do something like this:
>
>
> content.rst -   foo
> bar
> baz
>
>
> index.rst - .. toctree::
>:maxdepth: 2
>:hidden:
>.. include:: ./content.rst
>
>
> otherpage.rst- .. toctree::
>   :maxdepth: 4
>
>   .. include:: ./content.rst
>
> This seems not to work.  Is there a way to factor a toctree  directive 
> like this or am I forced to maintain two separate copies of the contents 
> (yuck)?
>
> Thanks
>

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

[sphinx-users] Re: Parsing inline literals

[Peter Burdine]

There are two other approaches that may work for you that I have used or 
seen people use:
1) Pass it through a pre-processer first to do replacements like that
2) Look into the jinja extension.  

In both cases the variables will be be replaced before docutils sees the 
reST.

On Friday, April 14, 2017 at 7:54:56 PM UTC-7, Mark Peters wrote:
>
> Hi,
>
> Is it possible to parse an inline literal to replace text using 
> substitution? 
>
> For example, our RST doc includes values that are updated periodically 
> such as:
>
> The policy must be stored in the ``/etc/debsig/policies/|GPG_KEY_ID|`` 
> directory
>
> .. |GPG_KEY_ID| replace:: 69BE019A
>
> The substitution text is interpreted, well, literally:
>
>
> I've tried using backslash-escaped whitespace, as follows, but the second 
> backslash escapes both the text and the second set of double-ticks:
>
> The policy must be stored in the ``/etc/debsig/policies/\ |GPG_KEY_ID|\ `` 
> directory
>
>
> I know to use the parsed-literal directive for code blocks. Is there an 
> option for inline literals? 
>
> Thanks,
> Mark
>
>
>
>
>
>
>

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

[sphinx-users] Re: Why does this warn? ":ref:" inside ".. only::"

[Peter Burdine]

Pete,

I may be a bit off on this, but I think the error is coming out during the 
resolving phase not the writing phase.  See 
http://www.sphinx-doc.org/en/stable/extdev/tutorial.html

I believe the HTML builder works mostly in phase 4 and it may be some other 
process trying to do the resolving in phase 3 that is generating the 
error.  If that is the case, the resolver can still see the :ref: and tries 
to resolve it since it can see the only node, but the html builder should 
skip it when visit_node is called.

--Peter

On Tuesday, March 14, 2017 at 10:18:12 AM UTC-7, Pete wrote:
>
> I only want to include the text with :ref:`installation` when building a 
> latex (or latexpdf) document.  So, when "make html" is run, this code::
>
> .. only:: latex
>
>See the section called :ref:`installation`.
>
> generates this warning::
>
> C:\Users\...\Introduction.rst:14: WARNING: undefined label: 
> installation (if the link has no caption the label must precede a section 
> header)
>
> When using the "html" builder, this line should not produce any output or 
> warnings or ... since it is inside the only directive that specifies a 
> different builder.  In truth, the installation label is *not* present.  
> That *would* be brought in to a the document under the same type of "only" 
> directive elsewhere.
>
> What have I misunderstood about the "only" directive?
> http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-only
>
> Here is another user who has the same assumption, that content within the 
> only directive will not be processed.
> https://trello.com/c/84v7OWVz/1335-sphinx-improve-only-directive-2150
>

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

[sphinx-users] Re: Relative paths - File not readable

[Peter Burdine]

We have to do this a lot since we have a library of sections that may need 
to be included in various documents.  We handle it by creating a "links" 
file that contains relative paths of links that it should create under the 
source directory.  Then we modified the make file to run a script that 
reads the "links" file and creates any required symbolic links.  Once that 
is done, you other directories appear under the source directory and thus 
can be included.  

On Monday, March 6, 2017 at 3:42:10 PM UTC-8, sajan mushini wrote:
>
> hey 
>  
>  A newbie here and I have the same issue. Any solution on this?
>
> Regards
> Sajan
> On Monday, 27 February 2012 07:11:28 UTC-7, Andersej wrote:
>>
>> Hi, 
>>
>> I have a question about the relative paths, and hope you can help. 
>>
>> In ~/project/doc/ I have index.rst and model.rst (model.rst is in 
>> toctree in index.rst). 
>>
>> Further, in ~/project/src/dynamics/ I have documentation.rst and 
>> plot.png. I include documentation.rst in model.rst using its relative 
>> path from /doc. 
>>
>> My question is then, is it possible somehow to include plot.png in 
>> documentation.rst, relative to documentation.rst itself (i.e. just .. 
>> image:: plot.png) without having to write the entire path to this 
>> directory again in a file already in the directory? 
>>
>> When I do this now, I get 
>>
>> ../src/dynamics/documentation.rst::11: WARNING: image file not 
>> readable: plot.png 
>>
>> -- 
>> Anders
>
>

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

[sphinx-users] Re: export individual pdf to each rst file

[Peter Burdine]

If you really wanted to do it with Sphinx, then you need to modify the 
latex ouput.  In your conf.py there should be a section with the following 
comments:

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).


You would need to add a tuple to the list for every .rst file.  You could 
probably automate this as manually trying to do it would be difficult to 
maintain.  Unless you have a very small number of files.  I think Bernhard 
is right though.  The power of Sphinx is to put files together and link 
them, I'm not sure why you would use it for each file.

On Wednesday, February 15, 2017 at 3:05:18 PM UTC-8, Aladdin Mhaimeed wrote:
>
> I could use sphinx-build to export all docs to one pdf,
> but my target is to export each rst file to a separate pdf file in a 
> similar tree like rst tree,
> any ideas?
> thanks
>

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

[sphinx-users] Re: How to use multiple paths for python modules documentation in different directories using sphinx autodoc?

[Peter Burdine]

Have you tried changing your sys.path to include both?  Eg:
sys.path.insert(0, os.path.abspath(".."))



Then for autodoc tried:
.. automodule:: python_modules_A

.. automodule:: python_modules_B



How you include documentation for it may then depend on your module 
structure (eg do you have an __init__.py? does it define __all__?)

On Wednesday, February 15, 2017 at 3:05:18 PM UTC-8, nshea wrote:
>
> I am using sphinx autodoc to document python modules in multiple 
> directories. I already have the rst files for each python module and can 
> use autodoc when declaring a path to one directory with the python modules 
> but I am trying to document python modules from two different directories. 
> In the conf.py file, I used:
>
>
> sys.path.insert(0, os.path.abspath("../python_modules_A"))
>
>
> but would like to have paths to both python_modules_A and 
> python_modules_B, since my modules are in both directories. Given the 
> structure of my project team, I would like to avoid having to restructure 
> the modules into one directory since they are separated by helper functions 
> in python_module_A and classes/objects for the main module python_modules_B 
> modules.
>
>
> Below is how my directories are configured:
>
>
> sphinx_doc_setup
>
>   conf.py
>
>   index.rst
>
>   a1.rst
>
>   b1.rst
>
>   a2.rst
>
>   b2.rst
>
> python_modules_A
>
>   a1.py
>
>   b1.py
>
> python_modules_B
>
>   a2.py
>
>   b2.py
>
>
> Thanks for any help!
>

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

[sphinx-users] Re: Metadata on inner front page

[Peter Burdine]

This was discussed in the last 2 weeks.  Please see these threads:
https://groups.google.com/forum/#!topic/sphinx-users/S_ip2b-lrRs
https://groups.google.com/forum/#!topic/sphinx-users/FpbnecT7qus

Please review those.  I believe there is enough information in those 
threads since they were addressing this topic.  If you still have 
questions, please reply here.

On Thursday, December 29, 2016 at 7:58:53 AM UTC-8, Antonis Christofides 
wrote:
>
> Hello, 
>
> I've written a book with sphinx. Is it possible to write stuff on the 
> inner 
> front page of the PDF produced with "make latexpdf"? Metadata that is, 
> such as 
> copyright and edition information. 
>
> In addition, how can I have unnumbered chapters, such as Foreword and 
> Appendix? 
>
> -- 
> Antonis Christofides 
> http://djangodeployment.com 
>
>

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

Re: [sphinx-users] Re: Actual, working example of latex-pdf cover page?

[Peter Burdine]

There should be a slightly less obvious way to do it.  I have considered 
doing it, but it makes the .rst files a bit more difficult to read.  Note 
that I have not tried this, it is only a guess at what you would need to do.

First redefine the latex_elements dict:
latex_elements = {
# ... put your stuff here
# Customize below for your template
'preamble': my_preamble,

# Redefine tableofcontents to be the commands you want to run
'tableofcontents': \make_title_page_only,   
 

# .. Anything else you want to do
}

Then in your preamble, define \make_title_page_only to print just the title 
page.  Eg remove \tableofcontents

Now, update your index.rst file to have a toctree that isn't numbered:
.. toctree::

copyright
trademark
main_toctree

Now you can put in your copyright, etc

Move the normal toctree into a separate file called main_toctree.rst (or 
pick a better name).  In that one, you probably want it numbered:
.. raw:: latex

\tableofcontents

.. toctree::
:numbered:
:glob:

put_your_previous_toctree_entries_here

Now your .rst files should build your html files and latex files in the 
same order and you *should* be able to have .rst content before your table 
of contents.  This now makes it a bit more difficult to get your 
header/footers correct (if you switch between roman/arabic numbers in you 
footers for example).  You maybe able work around this by including more .. 
raw:: latex directives.

If you go that route and it works, please let me know.

On Tuesday, December 20, 2016 at 7:03:13 AM UTC-8, Warren Block wrote:
>
> On Mon, 19 Dec 2016, Peter Burdine wrote: 
>
> > Yes, that is exactly why it is setup that way.  Remember that it is only 
> part of the solution.  The latex code still needs to in the preamble or a 
> style file and you need to overwrite the correct entry in the 
> latex_elements dict. 
> > 
> > This is only for latex output so none of this information is in .rst 
> files.   I am not sure what you meant by "Can this be used to control the 
> order of Sphinx-generated elements". 
>
> The hope was that it would allow putting a section of copyright and 
> trademark information before the table of contents, yet still being able 
> to write that section in rst for consistency with the rest of the 
> document and being able to generate both HTML and PDF output from it. 
>
> But no, it appears not. 
>
> > On Dec 19, 2016 5:03 PM, "Warren Block" <wbl...@wonkity.com 
> > wrote: 
> >   On Thu, 15 Dec 2016, Peter Burdine wrote: 
> > 
> >   Then I define the following for the front matter (note that some 
> of these are commands defined in the preamble or other included .tex/.sty 
> file): 
> > 
> >   latex_contents = r''' 
> >   \setupHeadFootForFrontMatter 
> >   \formattoc 
> >   \maketitle 
> >   \signaturepage 
> >   \revisionhistory 
> >   \tableofcontents 
> >   \clearpage 
> >   \listoffigures 
> >   \clearpage 
> >   \listoftables 
> >   \clearpage 
> >   \setupHeadFootForText 
> >   \pagenumbering{arabic} 
> >   \pagestyle{plain} 
> >   ''' 
> > 
> > 
> > Can this be used to control the order of Sphinx-generated elements, like 
> to put a copyright page before the table of contents?  (That can be done by 
> editing the generated .tex file, moving the call to \tableofcontents, but 
> that's ugly.)

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

[sphinx-users] Re: Creating a foreword

[Peter Burdine]

I think the root cause of this issue is the way the builders approach the 
documents.  HTML is a straight forward 1:1 translation, the latex builder 
kind of does the same thing.  The issue is that it is LaTeX that builds the 
table of contents and other front matter for the document (with the 
\tableofcontents command), then the contents are appended to the .tex 
file.  This is why the contents appears to be moved.  In the HTML builder, 
sphinx does all of the numbering and generating of the table of contents, 
but for latex, the builder writes out \part, \section, \subsection, etc and 
then latex builds the toc from there.  The latex toc only sees the 
definition of sections (titles only) not the rest of the content.  The 
content gets added only after the front matter.  If you watch the build 
output, you will see this as it lists each .rst file as it gets appended to 
the .tex file.  Hopefully this makes sense.  I've been playing with Sphinx 
for 3 months and it is only now making sense to me.

See this thread "how do I add revision history table? 
".  
While there are other threads the discuss front matter, this is the most 
recent.  AFAIK there is no obvious or easy way to do this.
https://groups.google.com/forum/#!topic/sphinx-users/DVAQTKpSens

The above thread will point you to writing all of that in Latex, that is 
not easy and doesn't translate to multiple output types.  After thinking 
about this for a bit, here is guess as to an approach that might work:
There should be a way to do it using the latex_documents field in the 
conf.py file.  There of course will be some confusion on how that works 
because you will then need to move your forward to another .rst file then 
use an .. include inside of an .. only:: html block to get it working for 
html, then do something differently for latex.  Then you will also need to 
redefine the latex commands to create the front matter.  Then you would 
then have to put some .. only:: latex blocks after the forward to reinsert 
the table of contents and other front matter in the correct locations 
before the document main content.

Now I am thinking about how I would want to do it, the HTML and Latex 
builder put things together so differently that this does not sound like an 
easy task.  If we can come up with a general approach I think that would 
help a lot of people.  I haven't played with anything other than 
html/latex, so I don't have any idea how the others work (though a forward 
and other front matter don't make really make sense for man/info pages).

--Peter

On Thursday, October 27, 2016 at 2:17:35 PM UTC-7, Warren Block wrote:
>
> We would like to include a foreword before the table of contents page 
> for a short introduction.  Coming before the TOC, this presumably would 
> not be listed in the TOC. 
>
> Including text in the index file before the toctree directive seemed 
> like a way to do this: 
>
>Document Sample 
>=== 
>
>Foreword 
> 
>
>Welcome to this document! 
>
>.. toctree:: 
>   :numbered: 
>   :maxdepth: 4 
>
>   intro 
>   ... 
>
>
> When rendered to PDF, the Foreword title appears as the first title of 
> the TOC, and the "Welcome to this document!" text appears as the first 
> text in the intro chapter. 
>
> Some searching found people asking how to accomplish this, but no clear 
> answers.  Can it be done? 
>
> The fall-back plan is to create a one-page PDF foreword and use a PDF 
> merge utility like pdftk to combine that with the PDF created by sphinx. 
> That's not elegant and introduces more dependencies.  Is there a better 
> way? 
>

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

Re: [sphinx-users] Re: Sphinx PDF themes

[Peter Burdine]

Sorry about that, now that I think about it, that requires the following in 
your preamble:
\usepackage{array,ragged2e}

Sorry about that, it is difficult to remember all of the requirements.  
Does that help?

On Wednesday, October 26, 2016 at 4:30:07 PM UTC-7, Warren Block wrote:
>
> On Wed, 26 Oct 2016, Peter Burdine wrote: 
>
> > The following worked fine for me: 
> > .. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 
> 0.3\linewidth-2\tabcolsep} 
> > |>{\RaggedRight}p{\dimexpr 
> 0.4\linewidth-2\tabcolsep} 
> > |>{\RaggedLeft}p{\dimexpr 
> 0.3\linewidth-2\tabcolsep}| 
> > 
> > .. _tasks_rsync_opts_tab: 
> > 
> > .. table:: Rsync Configuration Options 
> > :class: longtable 
> > 
> > ++--++ 
> > | Setting| Value| Description| 
> > ++--++ 
> > | Setting| Value| Description| 
> > ++--++   
>
> Not here, the same ! Undefined control sequence error as before.  My 
> guess is this is some TeX stuff that would normally be included from a 
> file that is not present on my system. 
>
> > Also, the commands are l, r, and c, not L, R, C.  So the following also 
> works: 
> > .. tabularcolumns:: |r|r|l| 
>
> In fairness, 
> http://www.sphinx-doc.org/en/1.4.8/markup/misc.html?highlight=tabularcolumns 
> shows this in an ambiguous form.  An example of actual usage would be 
> useful there.  Or in so many other places in the Sphinx docs. 
> Actually, the more I look at that explanation, the less clear it 
> becomes. 
>
> (Much experimentation later...) 
>
> The "p notation" vaguely mentioned in the docs is p{}, with a width 
> value and unit in the brackets, like 'p{1.0in}'.  Used alone, this value 
> specifies an absolute width for a column, with the default being 
> fill-justified, wrapped text in that column.  Example: 
>
>.. tabularcolumns:: |p{1.0in}|p{1.2in}|p{3.8in}| 
>
> That gives a three-column table with fill-justified, wrapped text in 
> each column. 
>
> 'l' and 'r' are used to left- or right-justify *and prevent wrapping*. 
> These letters can be added after the p{} width, but doing so resulted in 
> unpredictable column rendering.  I did not find a way to get specific or 
> relative column widths without fill-justification and word breaks. 
>
> The upper-case letters mentioned did not work in any context I tried, 
> with or without the p{} width.  It is not clear why they are shown at 
> all, or whether that is some misguided capitalization of a name that is 
> not actually meant to be capitalized. 
>
> > See https://en.wikibooks.org/wiki/LaTeX/Tables 
> > 
> > I always specify the width I want for PDF output to ensure that latex 
> doesn't do anything weird with the wrapping or have text run into the next 
> cell.  Normally I use 
> > list tables because I think they are easier to maintain (and contain 
> other nodes, like lists and admonitions), so I am not sure if the same 
> behavior happens with 
> > simple tables. 
> > 
> > On Tuesday, October 25, 2016 at 3:48:21 PM UTC-7, Warren Block wrote: 
> >   On Tue, 25 Oct 2016, Peter Burdine wrote: 
> > 
> >   > 
> >   > Please post the tabularcolumns directive you are using and 
> enough of the table definition to see the first header row.  There isn't 
> enough info to see 
> >   what the issue could be. 
> >   > 
> >   > One thing to verify is that the number of columns in the 
> tabularcolumns directive is the same as the actual table. 
> > 
> >   Sorry, here's a bit: 
> > 
> >  .. tabularcolumns:: |R|R|L| 
> > 
> >  .. _tasks_rsync_opts_tab: 
> > 
> >  .. table:: Rsync Configuration Options 
> > :class: longtable 
> > 
> > ++--++ 
> > | Setting| Value| Description| 
> > 
> > 
> >   This produces 
> > 
> >  ! Missing # inserted in alignment preamble. 
> >   
> > \cr 
> >  l.5164 \begin{longtable}{|p{1.0cm}|p{1.0cm}|L|} 
> > 
> >   The \RaggedRight colspec produces the "undefined control sequence" 
> shown 
> >   earlier.  Using |p{1.0cm}|p{1.0cm}|L| gives 
> > 
> >  ! Missing # inserted in alignment preamble. 
>

Re: [sphinx-users] Re: Sphinx PDF themes

[Peter Burdine]

The following worked fine for me:
.. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 0.3\linewidth-2\tabcolsep
}
|>{\RaggedRight}p{\dimexpr 0.4\linewidth-2\tabcolsep
}
|>{\RaggedLeft}p{\dimexpr 0.3\linewidth-2\tabcolsep
}|

.. _tasks_rsync_opts_tab:

.. table:: Rsync Configuration Options
:class: longtable

++--++
| Setting| Value| Description| 
++--++
| Setting| Value| Description|
++--++   

Also, the commands are l, r, and c, not L, R, C.  So the following also 
works:
.. tabularcolumns:: |r|r|l|

See https://en.wikibooks.org/wiki/LaTeX/Tables

I always specify the width I want for PDF output to ensure that latex 
doesn't do anything weird with the wrapping or have text run into the next 
cell.  Normally I use list tables because I think they are easier to 
maintain (and contain other nodes, like lists and admonitions), so I am not 
sure if the same behavior happens with simple tables.

On Tuesday, October 25, 2016 at 3:48:21 PM UTC-7, Warren Block wrote:
>
> On Tue, 25 Oct 2016, Peter Burdine wrote: 
>
> > 
> > Please post the tabularcolumns directive you are using and enough of the 
> table definition to see the first header row.  There isn't enough info to 
> see what the issue could be. 
> > 
> > One thing to verify is that the number of columns in the tabularcolumns 
> directive is the same as the actual table. 
>
> Sorry, here's a bit: 
>
>.. tabularcolumns:: |R|R|L| 
>
>.. _tasks_rsync_opts_tab: 
>
>.. table:: Rsync Configuration Options 
>   :class: longtable 
>
>   ++--++ 
>   | Setting| Value| Description| 
>
>
> This produces 
>
>! Missing # inserted in alignment preamble. 
> 
>   \cr 
>l.5164 \begin{longtable}{|p{1.0cm}|p{1.0cm}|L|} 
>
> The \RaggedRight colspec produces the "undefined control sequence" shown 
> earlier.  Using |p{1.0cm}|p{1.0cm}|L| gives 
>
>! Missing # inserted in alignment preamble. 
> 
>   \cr 
>l.5164 \begin{longtable}{|p{1.0cm}|p{1.0cm}|L|} 
>
> I have no preamble, so maybe it's that.  Or maybe another extension is 
> needed, at the moment only ifconfig and httpdomain are declared.  But 
> without the tabularcolumns directive, it does produce a PDF. 
>
> Thanks! 
>
> > On Oct 24, 2016 4:40 PM, "Warren Block" <wbl...@wonkity.com 
> > wrote: 
> >   On Mon, 10 Oct 2016, Peter Burdine wrote: 
> > 
> > Sphinx tables in latex are inconsistent at the moment.  
> There is a ticket open to use just one package for tables, but right now I 
> think it picks 1 of 4(?) packages depending on what it thinks it best.  In 
> all of the 
> > documentation we write, I always 
> > add :class: longtable to all of the table definitions to 
> allow for (what I think) is better layout, plus the header/footer for 
> continuations. 
> > 
> > You can format the columns and overall table width using the 
> tabularcolumns directive, eg 
> > .. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 
> 0.3\linewidth-2\tabcolsep} 
> > |>{\RaggedRight}p{\dimexpr 
> 0.5\linewidth-2\tabcolsep} 
> > |>{\RaggedRight}p{\dimexpr 
> 0.2\linewidth-2\tabcolsep}| 
> > 
> > Adding that everywhere tends to get annoying quickly, plus 
> is is difficult for most people understand what is going on (FYI this 
> produces a table with 3 columns, all left aligned, with 30%, 50%, and 20% 
> of the page widths). 
> > 
> > 
> > What else is needed to use this?  If I add it, PDF creation halts in the 
> middle, with 
> > 
> >   ! Undefined control sequence. 
> >...inewidth -2\tabcolsep }\RaggedRight 
> > \ignorespaces 
> >   l.5169 \textsf 
> > {\relax 
> >   ? 
> > 
> > This is sphinx 1.4.6. 
> > 
> > -- 
> > You received this message because you are subscribed to a topic in the 
> Google Groups "sphinx-users" group. 
> > To unsubscribe from this topic, visit 
> https://groups.google.com/d/topic/sphinx-users/LBGxmGESUhg/unsubscribe. 
> > To unsubscribe from this group and all its topics, send an email to 
> sphinx-users...@googlegroups.com . 
> > To post to this group, send

Re: [sphinx-users] Re: Sphinx PDF themes

[Peter Burdine]

Please post the tabularcolumns directive you are using and enough of the
table definition to see the first header row.  There isn't enough info to
see what the issue could be.

One thing to verify is that the number of columns in the tabularcolumns
directive is the same as the actual table.

On Oct 24, 2016 4:40 PM, "Warren Block" <wbl...@wonkity.com> wrote:

On Mon, 10 Oct 2016, Peter Burdine wrote:

Sphinx tables in latex are inconsistent at the moment.  There is a ticket
> open to use just one package for tables, but right now I think it picks 1
> of 4(?) packages depending on what it thinks it best.  In all of the
> documentation we write, I always
> add :class: longtable to all of the table definitions to allow for (what I
> think) is better layout, plus the header/footer for continuations.
>
> You can format the columns and overall table width using the
> tabularcolumns directive, eg
> .. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 0.3\linewidth-2\tabcolsep}
> |>{\RaggedRight}p{\dimexpr 0.5\linewidth-2\tabcolsep}
> |>{\RaggedRight}p{\dimexpr 0.2\linewidth-2\tabcolsep}|
>
> Adding that everywhere tends to get annoying quickly, plus is is difficult
> for most people understand what is going on (FYI this produces a table with
> 3 columns, all left aligned, with 30%, 50%, and 20% of the page widths).
>

What else is needed to use this?  If I add it, PDF creation halts in the
middle, with

  ! Undefined control sequence.
   ...inewidth -2\tabcolsep }\RaggedRight
\ignorespaces
  l.5169 \textsf
{\relax
  ?

This is sphinx 1.4.6.


-- 
You received this message because you are subscribed to a topic in the
Google Groups "sphinx-users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/to
pic/sphinx-users/LBGxmGESUhg/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
sphinx-users+unsubscr...@googlegroups.com.
To post to this group, send email to sphinx-users@googlegroups.com.
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

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

[sphinx-users] Re: Adding background color of notes and attention to Sphinx-generated PDF files

[Peter Burdine]

\usepackage{xcolor}

...

\makeatletter
\definecolor{shadecolor}{RGB}{220,220,220}

...

\renewcommand{\py@noticestart@note}{\py@lightbox\begin{snugshade*}}
\renewcommand{\py@noticeend@note}{\end{snugshade*}\py@endlightbox}

...

\makeatother

Adding the above to your preamble will enable "notes" to have a background 
color.  Using the above, you should be able to figure out the other 
admonitions.  Note that this is only one method of doing it, I'm sure there 
are others.

On Wednesday, October 12, 2016 at 5:33:15 PM UTC-7, Peter Burdine wrote:
>
> This is where you need to learn about LaTeX.  Those commands include the 
> character '@', so you need "\makeatletter" before those commands and 
> "\makeatother" after those commands.  The @ sign is a special character in 
> LaTeX, so you need to tell the system that you are using it as a letter, 
> then put it back into the regular mode.  I don't recall the special terms 
> that I should be using here, but hopefully the point comes across.
>
> On Wednesday, October 12, 2016 at 1:04:29 AM UTC-7, Minkai Li wrote:
>>
>> I add this commands to my conf.py preamble,But it does not work. It can 
>> not compile. I use restructuredtext and sphinx in Ubuntu environment
>>
>> 在 2016年10月12日星期三 UTC+8上午7:34:18，Peter Burdine写道：
>>>
>>> You will need to add some Latex commands to your preamble.  For example, 
>>> the following will make notes centered:
>>> \renewcommand{\py@noticestart@note}{\py@lightbox\begin{center}}
>>> \renewcommand{\py@noticeend@note}{\end{center}\py@endlightbox}
>>>
>>> This will make the admonition title be upper case:
>>> \renewenvironment{notice}[2]{
>>>   \def\py@noticetype{#1}
>>>   \csname py@noticestart@#1\endcsname
>>>   % Make the admonition type be upper case and on its own line
>>>   \strong{\MakeUppercase{#2}} \\
>>> }{\csname py@noticeend@\py@noticetype\endcsname}
>>>
>>> Modifying the PDF output of Sphinx isn't easy because you have to do a 
>>> few things:
>>>
>>>- Learn enough Latex to understand the Sphinx style files
>>>- Learn enough Latex to do what you want
>>>- Figure out how to modify it using a preamble that doesn't break 
>>>the output
>>>
>>> So far there isn't any general guide on how to do it.
>>>
>>>
>>> On Monday, October 10, 2016 at 5:10:16 PM UTC-7, Minkai Li wrote:
>>>>
>>>> I am able to generate notes using the Sphinx directive .. notes:: and 
>>>> .. attention::. However, the notes and the attention in html file have 
>>>> a background color while those from the generated PDF don’t. How can I add 
>>>> color to Sphinx-generated PDF files? Is it in conf.py?
>>>>
>>>

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

[sphinx-users] Re: how do I add revision history table?

[Peter Burdine]

In the latex output, all of the front matter ouput (title page, toc, etc) 
is controlled by the \maketitle command.  If you want to change the front 
matter you need to renew that command to change its behavior.

On Friday, October 14, 2016 at 4:41:39 PM UTC-7, Fiona Hanington wrote:
>
> Hi there
> I would like to include a revision history table as part of the front 
> matter of my documents (PDF). I'd like this to appear after the title page 
> and before the toc if possible. Does sphinx/rst support this? If so how 
> would I go about it?
> Thanks
> Fiona
>

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

[sphinx-users] Re: sphinx pdf style

[Peter Burdine]

The short answer is not in 1.4.x.  It looks like 1.5.x may have a little, 
but nothing as easy as CSS.  Start by reading through the sphinx.sty file 
(found in your latex build directory) to give you an idea of what you are 
dealing with.

It looks like you have made 6 threads all with basically the same (very 
open-ended)  question.  Customizing LaTeX content is not an easy task.  
Please start by looking at other open source project examples.  Here are 
some example projects that I have used while learning.  Note that some of 
them will have addition prereqs (either Python or LaTeX libraries).

   - https://github.com/mapserver/docs
   - https://github.com/i6/ibg



On Friday, October 14, 2016 at 1:47:01 AM UTC-7, Minkai Li wrote:
>
> Sphinx generate pdf ,does this pdf has some  templates such as sphinx 
> generate html use css files 
>

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

[sphinx-users] Re: how do I add subtitle?

[Peter Burdine]

Yes and no.

In the latex section of the conf.py, you will see a latex_elements dict 
being defined.  This is where you can modify your preamble.  You can put 
your definition there, but most people read in a separate file or two, 
since when you update your document format, the changes can be extensive 
and difficult to read in the conf.py.

My approach thus far was to create my own .sty to has commands to change 
the headers/footers, and redefines \maketitle (which you can see part of in 
the previous post).  The title is written on the page with this:
\begin{center}%
  \sphinxlogo%
  {\rm\Huge\py@HeaderFamily \@title \par}%
  {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par}

Which you can see in the sphinx.sty file.  This is probably where you would 
want to put in a subtitle.  Note the Sphinx defines \@title, \py@release, 
and \releaseinfo for you.  If you want any other variables, you will need 
to define them in your preamble.  You get this added to your build 
directory by modifying the latex_additional_files list in the conf.py:
latex_additional_files = ['your_sty_file.sty', 
 ]


I have followed other examples, by making the preamble its own .tex file 
and treating that as string.Template object, so in my conf.py I have the 
following:
PREAMBLE = string.Template(open(
os.path.join(os.path.abspath('.'),
'latex_templates/preamble.tex')
).read())

Then in the latex_elements dict in the conf.py I have:
latex_elements = {
 ...
'preamble': PREAMBLE.substitute(...), 
...
}

Please look at some open source examples online for how other people have 
their projects setup:

   - https://github.com/mapserver/docs
   - https://github.com/i6/ibg

You can probably find more examples online.  These are two that I have read 
through and found helpful.


On Thursday, October 13, 2016 at 1:09:00 PM UTC-7, Fiona Hanington wrote:
>
> Thank you for this!!   I do want a subtitle on the cover page of a PDF 
> doc.   What file to I update with the content you've given?  (conf.py?)  
>
> On Wednesday, 12 October 2016 17:33:08 UTC-7, Peter Burdine wrote:
>>
>> Can you clarify what you mean by "subtitle"?
>>
>> The reST you posted (assuming it is all in one file) says make a Heading 
>> 1 ('Title'), followed by a Heading 2 ('subtitle') followed by a Heading 1 
>> ('subsubtitle').  This is because you used the same character ('*') for 
>> heading 1, then used it again for, for what looks like it should be, a 
>> heading 3.  In reST, any 4 consecutive characters that begin a line can be 
>> used as a heading indicator.  Overlines are optional, underlines are 
>> manditory and need to be at least as long as the text they are trying to 
>> over/underline.  If you use overlines, then they need to be the same length 
>> as the underline.  If you follow the python guidelines, then use # for 
>> heading 1, * for heading 2, and = for heading 3 (IIRC).
>>
>> It looks like you are trying to build a PDF from your question.  If 
>> someone asked about a subtitle for PDF output, then I assume that they mean 
>> some some text that is slightly smaller than the title, on the title page.  
>> If this is what you want, you will need to modify your preamble to redefine 
>> \maketitle.
>>
>> \renewcommand{\maketitle}{%
>>   \begin{titlepage}%
>>
>>   % Put your content here
>>
>>   \end{titlepage}%
>>   \cleardoublepage%
>>   \setcounter{footnote}{0}%
>>   \let\thanks\relax\let\maketitle\relax
>>   %\@ifundefined{fancyhf}{}{\pagestyle{normal}}%
>> }
>>
>> You can find the default definition in one of the .sty files that is 
>> included with Sphinx.
>>
>> On Wednesday, October 12, 2016 at 4:27:53 PM UTC-7, Fiona Hanington wrote:
>>>
>>> Hi
>>>
>>> (Excuse the newby question -- I am new to rst and sphinx and the person 
>>> who set things up here has left, so I am trying to work things out.)
>>>
>>> I need to add a subtitle to an existing doc.
>>>
>>> Sphinx docs on the internet tell me that to add a title/subtitle, I 
>>> simply need to add this to my "file":
>>>
>>> *
>>> Title
>>> *
>>>
>>> subtitle
>>> 
>>>
>>> subsubtitle
>>> ***
>>> and so on
>>>
>>>
>>>
>>> However, I don't know where to add this.  If I look at my conf.py file, 
>>> which currently has a project name that controls the doc title, it looks 
>>> like this (title is not formatted as suggested above). Title is defined by 
>>> what is in *project = *:
>>

[sphinx-users] Re: Sphinx PDF themes

[Peter Burdine]

Sphinx tables in latex are inconsistent at the moment.  There is a ticket 
open to use just one package for tables, but right now I think it picks 1 
of 4(?) packages depending on what it thinks it best.  In all of the 
documentation we write, I always add :class: longtable to all of the table 
definitions to allow for (what I think) is better layout, plus the 
header/footer for continuations.

You can format the columns and overall table width using the tabularcolumns 
directive, eg
.. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 0.3\linewidth-2\tabcolsep}
|>{\RaggedRight}p{\dimexpr 0.5\linewidth-2\tabcolsep}
|>{\RaggedRight}p{\dimexpr 0.2\linewidth-2\tabcolsep}|

Adding that everywhere tends to get annoying quickly, plus is is difficult 
for most people understand what is going on (FYI this produces a table with 
3 columns, all left aligned, with 30%, 50%, and 20% of the page widths).

IIRC, xcolor doesn't work with all table packages, hence why it might be 
working for you.  I'd have to look through the latex writer code to find 
all of the table packages that are used, but it possible that it may work 
with one of the table packages, then you could use the :class: option to 
always use that package.

On Saturday, October 8, 2016 at 4:23:53 PM UTC-7, Minkai Li wrote:
>
> sphinx can generate Latex,the pdf it produces via latex, I'm using sphinx 
> to generate documentations. The tables it produces via latex are pretty ugly, 
> so I'd like to give them some global styling. I'd like to 
> customize tableheader row color.I add the directive 
> 在此输入代\usepackage{tabu,tabulary}码...\usepackage[table]{xcolor}\definecolor{
> tablehead}{rgb}{153,153,153 } 
>
> into my conf.py peramble  but it does not work.
>
>
> 在 2016年10月7日星期五 UTC+8上午8:23:47，Peter Burdine写道：
>>
>> For Sphinx, most people create a preamble.tex file that modifies the 
>> formatting Sphinx uses.  As of 1.4.x of Sphinx, there isn't much in the way 
>> of global styling options.  You have to learn a bit of Latex.
>>
>> On Thursday, October 6, 2016 at 5:32:08 AM UTC-7, Minkai Li wrote:
>>>
>>> Does the Sphinx documentation tool offer different PDF themes？Sphinx 
>>> doesn't generate PDF output by itself，Ituse the Latex builder。How to set 
>>> the sphinx pdf themes?
>>>
>>

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

[sphinx-users] Re: Sphinx PDF themes

[Peter Burdine]

For Sphinx, most people create a preamble.tex file that modifies the 
formatting Sphinx uses.  As of 1.4.x of Sphinx, there isn't much in the way 
of global styling options.  You have to learn a bit of Latex.

On Thursday, October 6, 2016 at 5:32:08 AM UTC-7, Minkai Li wrote:
>
> Does the Sphinx documentation tool offer different PDF themes？Sphinx 
> doesn't generate PDF output by itself，Ituse the Latex builder。How to set 
> the sphinx pdf themes?
>

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

[sphinx-users] Re: Custom JSON output?

[Peter Burdine]

Can you describe your starting point and goals a bit more?  It looks like 
you may be trying to autodoc source code in json format?

If that is the case, then you might want to look at the source for the 
napolean extension (well, it is built into sphinx now).  
https://pypi.python.org/pypi/sphinxcontrib-napoleon
That seems to get all of the data you want.  

Or instead of building a new builder, you could use the napolean extension 
to build your documents and output it in xml or pseudoxml, then post 
process the output in the above format (xml -> json isn't too difficult).


On Wednesday, September 7, 2016 at 7:18:02 AM UTC-7, Thomas Schultz wrote:
>
> Hello!
>
> I'm working on a project that has sphinx generated documentation and we 
> are trying to also make a JSON output of these docs with a very specific 
> format.
>
>
> Example of desired JSON output:
> {
> "description": "\n Define API Queries.",
> "examples": [],
> "id": "google.cloud.bigquery.query.queryresults",
> "methods": [{
> "examples": [],
> "exceptions": [],
> "id": "google.cloud.bigquery.query.QueryResults.__init__",
> "name": "__init__",
> "params": [],
> "returns": [],
> "source": "google/cloud/bigquery/query.py#L60",
> "type": "instance"
> }, {
> "examples": [],
> "exceptions": [],
> "id": "google.cloud.bigquery.query.QueryResults.fetch_data",
> "name": "fetch_data",
> "params": [{
> "description": " token representing a cursor into the table's 
> rows.",
> "name": "page_token",
> "nullable": null,
> "optional": null,
> "types": ["string or NoneType"]
> }]
> }]
> }
>
>
> I attempted to make a custom builder for this a while ago but I wasn't 
> able to access the above pieces of data in a predictable way.
>
> If you have any resources you could point me towards or suggestions, I 
> would be very grateful!
>
>
> Thank you!
>

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

[sphinx-users] Re: Role functions have an inliner, how do I get it from within a Directive?

[Peter Burdine]

import sphinx
from docutils import nodes
from docutils.parsers.rst import Directive
from docutils.parsers.rst import directives
from docutils.statemachine import ViewList

class CustomDirective(Directive):

has_content = True
required_arguments = 1
option_spec = {

}
app = None

def run(self):
node = nodes.Element()
node.document = self.state.document
env = self.state.document.settings.env
docname = env.docname
new_content='\n'.join(self.content)
sphinx.util.nodes.nested_parse_with_titles(self.state, 
   ViewList(new_content.
splitlines(), source=docname),
   node)
   
return node.children

I think the above is about the smallest example possible.  It will take the 
content of the directive and render it as reST.

--Peter

On Tuesday, September 6, 2016 at 11:45:06 AM UTC-7, Jason S wrote:
>
> Custom role functions have an inliner:
>
>   def myrole(role, rawtext, text, lineno, inliner, options={}, content=[]):
>
>   ...
>
>
> But what about a custom Directive? How can I get the inliner from within the 
> run() function? I need to call inliner.nested_parse().
>
>
>

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

[sphinx-users] Re: Display section number in reference?

[Peter Burdine]

https://github.com/sphinx-doc/sphinx/issues/326

On Wednesday, August 24, 2016 at 11:25:17 AM UTC-7, Jason S wrote:
>
> +1
>
> On Wednesday, June 10, 2015 at 4:12:50 AM UTC-7, Andrea Cassioli wrote:
>>
>> Hi,
>> I am struggling to find a simpler workaround that using a custom 
>> extension for this problem:
>>
>> I would like to refer to sections and get as link label the section 
>> number instead of the caption, for instance
>>
>> .. _mysection:
>>
>> Title
>> ==
>>
>> some text
>>
>> in some other place I'd like to say
>>
>>
>> see section :ref:`mysection`
>>
>> but getting as output
>>
>>
>>> see section 3
>>
>>
>> I know that there is some extension on github for that, but it seems to 
>> me such a basic functionality that I wonder whether I miss something. 
>>  
>>
>

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

Re: [sphinx-users] genindex in latexpdf

[Peter Burdine]

That is exactly how I handle it as well:

.. only:: html

-
Indexes
-
   
* :ref:`genindex`
* :ref:`search`




On Wednesday, August 10, 2016 at 5:53:14 PM UTC-7, Paolo Cavallini wrote:
>
> Il 28/07/2016 12:38, Paolo Cavallini ha scritto: 
>
> > Issue found (thanks Matteo): an option is missing from conf.py 
> > 
> > # -- Options for LaTeX output 
> - 
> > latex_elements = { 
> > 'babel':'\\usepackage[shorthands=off]{babel}', 
> > 
> > Adding it solves the error and the index is correctly generated. 
>
> Shouldn't this be added by default? 
>
> > However, I still have an issue: the pdf has an extra page, before the 
> > actual index, with an useless: 
> > 
> > Indici 
> > • genindex 
> > 
> > if I remove from index.rst the lines: 
> > 
> > Indici 
> > == 
> > 
> > * :ref:`genindex` 
> > 
> > the page disappears, and only the correct index is displayed. 
> > In html, however, the index disappears in the second case. 
> > I think the same index should be used for html and latexpdf, and only 
> > the correct index page should always be generated, so this seems a bug: 
> > do you agree? 
> > 
> > Should I open tickets about this? 
>
> Ticket opened: 
> https://github.com/sphinx-doc/sphinx/issues/2827 
> As a workaround, I tried using .. only:: directive 
>
> http://www.sphinx-doc.org/en/stable/markup/misc.html#including-content-based-on-tags
>  
> to include 
>
> Indici 
> == 
>
> * :ref:`genindex` 
>
> only in html, but I could not understand which syntax to use. I'd be 
> grateful of an example. 
>
> All the best. 
>
> -- 
> Paolo Cavallini - www.faunalia.eu 
> QGIS & PostGIS courses: http://www.faunalia.eu/training.html 
>

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

[sphinx-users] Re: rst_epilog, replacing text, ifconfig, dealing with environmental variables.

[Peter Burdine]

For the documentation I have been writing, I couldn't get ifconfig or 
replacements to do what I wanted do.  I have some variation on how things 
work and ifconfig was pretty limited.  I didn't like replace either because 
it make it difficult to use it in directives.  Eg:
.. parsed-literal::

|replaceme|

Doing this would change this from a verbatim block to a text block.  So it 
would lose all formatting properties (no box, no shading, etc).  This also 
means code-blocks and other things didn't work.  For the above, I could 
then do:

.. code-block:: context

{{ variables_from_yaml_context }}


Instead, I've used the sphinx-jinja extension 
(https://pypi.python.org/pypi/sphinx-jinja/0.2.1 
https://github.com/tardyp/sphinx-jinja).  It allows you to store data in 
YAML format, and then use that inside of your rst files.  That said, it is 
one more thing for you learn.  It doesn't do everything I want, but it does 
enough.  It gives you iterators, conditionals, filters and some other 
things that will writing documentation with variations easier.

I've submitted a PR against it to make some improvements (adding debugging, 
ability to include other files from jinja, etc).  

You may find it useful.


On Tuesday, July 26, 2016 at 5:03:23 AM UTC-7, Chris P wrote:
>
> Hello.
>
> I've scoured the docs and don't see anything that will quite do what I'm 
> looking for. I've been at this a few days and am hoping someone here can 
> help me. 
>
> Let's say I'm writing documentation for a pet store software package. I'm 
> trying to build two sets of documentation: one for dog/llama owners, one 
> for cat owners. I'm building html docs using *make -e html*. This should 
> bring in the myPet environmental variable. 
>
> If I make a static *.. |myPet| replace:: |myCat|* entry in rst_epilog, I 
> get the output I'm after. But I really want to do something like *.. 
> |myPet| replace:: '|' += os.environ.get('myPet') += '|'*
>
> *Right now, ifconfig has the desired outcome, but replacement (in conf.py, 
> rst_epilog) doesn't work. How can I make replacement work (e.g. dynamically 
> .. |myPet| replace:: |myCat|)?* *Yes, I could probably hack together a 
> sed/awk script to change these lines in conf.py, but there must be a better 
> way.*
>
> I would much rather type out:
>
> *Thanks for buying a fuzzy pet who says |myPet|!* 
>
>
> rather than something like 
>
> *Thanks for buying a fuzzy pet who says *
>
>  
>
> *.. ifconfig:: myPet in ('|myCat|')*
>
> *   Meow*
>
> *.. ifconfig:: myPet in ('|myDog|')*
>
> *   Woof*
>
> *!*
>
>
> *Environment*: 
>
> $ printenv | grep "myPet"
> myPet=myCat
>
>
> *conf.py*:
>  
>
>> myPet= u''
> def setup(app):
> app.add_config_value('myPet', '', 'env')
>
> myPet += os.environ.get('myPet')
>
> rst_epilog = """
>
> .. |myCat| replace:: Meow
> .. |myDog| replace:: Woof
>
> """ 
>
>
> *Information.rst*: 
>
> This software is designed to run on Windows, Mac OS and Linux. 
>
> .. ifconfig:: myPet in ('|myCat|')
>
>In order to install this software, the **Cat** must be installed on 
> your system.
>
> .. ifconfig:: myPet in ('|myDog|')
>
>In order to install this software, the **Dog** must be installed on 
> your system.
>
>
> *Changelog.rst*:
> * Better pet store algorithm
>
> .. ifconfig:: myPet in ('|myCat|')
>
>* |PETSTOREFeatureNew| Improved meowing sounds
>* |PETSTOREFeatureNew| Improved hissing sounds
>
> .. ifconfig:: myPet in ('|myDog|', '|myLlama|')
>
>* |PETSTOREFeatureNew| Improved slobber effect
>
> * Minor Fixes
>

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

Re: [sphinx-users] iftex.sty is required by not delivered with 1.4.3?

[Peter Burdine]

I'm sure everyone figured this out, but this was fixed in 1.4.4.

On Tuesday, June 7, 2016 at 3:40:27 PM UTC-7, Peter Burdine wrote:
>
> For now, I've downloaded the iftex.sty from the above referenced site and 
> added to the latex_additional_files list in the conf.py.  That seems to 
> work ok, but it is a pain to do this for all of the projects.
>
> This new requirement looks like it was related to 
> https://github.com/sphinx-doc/sphinx/pull/2590.
>
> I created an issue for this: 
> https://github.com/sphinx-doc/sphinx/issues/2639
>
> On Tuesday, June 7, 2016 at 8:26:31 AM UTC-7, Jeff McKenna wrote:
>>
>> I have hit the exact same issue with 1.4.3 (on our Travis CI remote 
>> builds, which run Ubuntu Precise I believe).   
>>
>> -jeff
>>
>>
>>
>>
>>
>> On Tue, Jun 7, 2016 at 11:01 AM, Peter Burdine <pbur...@gmail.com> wrote:
>>
>>> I just upgraded from 1.4.1 to 1.4.3 (running in cygwin).  When 
>>> attempting to build a PDF, I am now getting:
>>> ! LaTeX Error: File `iftex.sty' not found.
>>>
>>> I am assuming it is referring to 
>>> https://www.ctan.org/tex-archive/macros/latex/contrib/iftex?lang=en.  
>>> Is this file supposed to be included with Sphinx now or do I have to tell 
>>> all my users they have more configuration to do?
>>>
>>> Thanks,
>>> Peter
>>>
>>> -- 
>>> You received this message because you are subscribed to the Google 
>>> Groups "sphinx-users" group.
>>> To unsubscribe from this group and stop receiving emails from it, send 
>>> an email to sphinx-users...@googlegroups.com.
>>> To post to this group, send email to sphinx...@googlegroups.com.
>>> Visit this group at https://groups.google.com/group/sphinx-users.
>>> For more options, visit https://groups.google.com/d/optout.
>>>
>>
>>

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

[sphinx-users] Re: Help changing title of the index.html

[Peter Burdine]

Look at your index.rst, it should be the first header in there.

On Wednesday, June 15, 2016 at 12:18:05 AM UTC-7, Protik Das wrote:
>
>
> Hi everyone! I am trying to design my homepage 
>  which is primarily going to be 
> documentation of a tool named VASP. As it is my homepage, I would like to 
> change the "Docs" name below to something like "Home". I already tried, ".. 
> title:: Homepage of Protik", but it doesn't change it. Can someone help me 
> changing it?
>
>
>
>
>  
>
> Thanks!
>

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

Re: [sphinx-users] can I use sphinx as wiki?

[Peter Burdine]

sphinx-autobuild is at https://github.com/GaretJax/sphinx-autobuild

I haven't looked at those wiki's, but it would be wise to check if you are 
using sphinx specific tags that are not part of reST or if you are using 
any extensions.  Those may not work if you are using a reST based wiki.

On Thursday, June 9, 2016 at 6:48:15 PM UTC-7, gsavix wrote:
>
> hhuumm!! good information. please have one url for all of us see more 
> details? regards.
>
> 2016-06-09 15:56 GMT-03:00 Peter Burdine <pbur...@gmail.com >
> :
>
>> If you haven't tried it, you might want to look at the sphinx-autobuild 
>> extension.  It seems to work pretty well, it will start up its own 
>> webserver and issue an html rebuild anytime a file is modified.
>>
>> I have noticed though if you use the sphinx-jinja extension, changing the 
>> source of the context will trigger a rebuild, but won't necessarily rebuild 
>> the affected content.  You can make one small tweak to the plugin, change 
>> 'html' in the setup function to say 'env', then it works as expected.
>>
>> If you don't have too many people, you may be able to use that as a wiki.
>>
>> On Monday, May 9, 2016 at 3:26:53 PM UTC-7, Chris Barker - NOAA Federal 
>> wrote:
>>>
>>> No, Sphinx is not a wiki system.
>>>
>>> The defining feature of a wiki is that users can edit the pages on the 
>>> fly in the same web app that is presenting the pages. Sphinx generates 
>>> static content, and does not provide an interface for editing it.
>>>
>>> That being said, it may be useful for your use-case.
>>>
>>> If you put your Sphinx content in a gitHub repo, you can serve up the 
>>> rendered html with gitHub pages, and your users/contributors can edit the 
>>> content with gitHub's interface, OR by cloning the repo and doing the usual 
>>> PR dance that is used for code.
>>>
>>> If your contributors are fairly sophisticated or used to the gitHub 
>>> workflow, this can work well.
>>>
>>> Alternatively, there may well be a wiki system that allows RST as the 
>>> markup language -- maybe even gitHub's wiki.
>>>
>>> -CHB
>>>
>>> On May 9, 2016, at 7:54 AM, Renato Pontefice <renato.p...@gmail.com> 
>>> wrote:
>>>
>>> Hi,
>>> I would start to use a wiki to write documentation on my softwarehouse.
>>> My Idea is to use restructuredtex, because is most useful (I can 
>>> translate it on pdf, word etc...)
>>>
>>> So my wiki reference is moinmoin. 
>>> I saw that moinmoin is quite at release 2, but still release 1.9.x
>>>
>>> My question is:
>>> Could Sphinx be a wiki?
>>> Or, it is lust a "trasformation" software?
>>>
>>> I hope I was clear
>>>
>>> TIA
>>>
>>> Renato
>>>
>>> -- 
>>> You received this message because you are subscribed to the Google 
>>> Groups "sphinx-users" group.
>>> To unsubscribe from this group and stop receiving emails from it, send 
>>> an email to sphinx-users...@googlegroups.com.
>>> To post to this group, send email to sphinx...@googlegroups.com.
>>> Visit this group at https://groups.google.com/group/sphinx-users.
>>> For more options, visit https://groups.google.com/d/optout.
>>>
>>> -- 
>> You received this message because you are subscribed to the Google Groups 
>> "sphinx-users" group.
>> To unsubscribe from this group and stop receiving emails from it, send an 
>> email to sphinx-users...@googlegroups.com .
>> To post to this group, send email to sphinx...@googlegroups.com 
>> .
>> Visit this group at https://groups.google.com/group/sphinx-users.
>> For more options, visit https://groups.google.com/d/optout.
>>
>
>
>
> -- 
> gilberto dos santos alves
> +55(11)9-8646-5049
> sao paulo - sp - brasil
>
>
>
>
>

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

[sphinx-users] Re: parsed-literal/code-block and other preformated block in PDF Output

[Peter Burdine]

I guess this is a feature "by design":

> (DefaultSubstitutions won't help, since these are used as Text nodes as 
> well.)
>

>From https://github.com/sphinx-doc/sphinx/issues/2173


On Monday, May 16, 2016 at 4:52:21 PM UTC-7, Peter Burdine wrote:
>
> I think this is related to 
> https://github.com/sphinx-doc/sphinx/issues/2167 that Andrea put in last 
> year.
>
> On Saturday, May 14, 2016 at 10:27:47 AM UTC-7, Peter Burdine wrote:
>>
>> Is there a way to either completely enable or disable syntax-highlighting 
>> for parsed-literal and code-blocks?  I am running into an issue where I 
>> have to use parsed-literal directives because I need some formatting in 
>> code blocks to show which words are variables, eg something like this:
>>
>> .. parsed-literal::
>>
>> # cd *someDirectory*
>>
>> In other places I used rst replacements like:
>>
>> .. parsed-literal::
>> 
>> # cd |directory|
>>
>> In the first example, in the PDF output it shows up like a normal code 
>> block (black border, syntax highlighting, etc), but the second example 
>> doesn't
>>
>> In the .tex file for the marked up parsed-literal it looks like:
>> \begin{Verbatim}[commandchars=\\\{\}]
>> ...content here...
>> \end{Verbatim}
>>
>> But in the parsed-literal with the substitution, it renders like:
>> \begin{alltt}
>> ...content here...
>> \end{alltt}
>>
>> The same thing happens in HTML output (though not as noticible).  The 
>> marked up parsed-literal gets rendered with 'default-highlight' but the one 
>> with the replacement gets rendered with 'literal-block'.
>>
>> Is there a way to force to do one or the other?  
>>
>>
>>

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

Re: [sphinx-users] can I use sphinx as wiki?

[Peter Burdine]

If you haven't tried it, you might want to look at the sphinx-autobuild 
extension.  It seems to work pretty well, it will start up its own 
webserver and issue an html rebuild anytime a file is modified.

I have noticed though if you use the sphinx-jinja extension, changing the 
source of the context will trigger a rebuild, but won't necessarily rebuild 
the affected content.  You can make one small tweak to the plugin, change 
'html' in the setup function to say 'env', then it works as expected.

If you don't have too many people, you may be able to use that as a wiki.

On Monday, May 9, 2016 at 3:26:53 PM UTC-7, Chris Barker - NOAA Federal 
wrote:
>
> No, Sphinx is not a wiki system.
>
> The defining feature of a wiki is that users can edit the pages on the fly 
> in the same web app that is presenting the pages. Sphinx generates static 
> content, and does not provide an interface for editing it.
>
> That being said, it may be useful for your use-case.
>
> If you put your Sphinx content in a gitHub repo, you can serve up the 
> rendered html with gitHub pages, and your users/contributors can edit the 
> content with gitHub's interface, OR by cloning the repo and doing the usual 
> PR dance that is used for code.
>
> If your contributors are fairly sophisticated or used to the gitHub 
> workflow, this can work well.
>
> Alternatively, there may well be a wiki system that allows RST as the 
> markup language -- maybe even gitHub's wiki.
>
> -CHB
>
> On May 9, 2016, at 7:54 AM, Renato Pontefice  > wrote:
>
> Hi,
> I would start to use a wiki to write documentation on my softwarehouse.
> My Idea is to use restructuredtex, because is most useful (I can translate 
> it on pdf, word etc...)
>
> So my wiki reference is moinmoin. 
> I saw that moinmoin is quite at release 2, but still release 1.9.x
>
> My question is:
> Could Sphinx be a wiki?
> Or, it is lust a "trasformation" software?
>
> I hope I was clear
>
> TIA
>
> Renato
>
> -- 
> You received this message because you are subscribed to the Google Groups 
> "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an 
> email to sphinx-users...@googlegroups.com .
> To post to this group, send email to sphinx...@googlegroups.com 
> .
> Visit this group at https://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/d/optout.
>
>

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

Re: [sphinx-users] iftex.sty is required by not delivered with 1.4.3?

[Peter Burdine]

For now, I've downloaded the iftex.sty from the above referenced site and 
added to the latex_additional_files list in the conf.py.  That seems to 
work ok, but it is a pain to do this for all of the projects.

This new requirement looks like it was related to 
https://github.com/sphinx-doc/sphinx/pull/2590.

I created an issue for this: 
https://github.com/sphinx-doc/sphinx/issues/2639

On Tuesday, June 7, 2016 at 8:26:31 AM UTC-7, Jeff McKenna wrote:
>
> I have hit the exact same issue with 1.4.3 (on our Travis CI remote 
> builds, which run Ubuntu Precise I believe).   
>
> -jeff
>
>
>
>
>
> On Tue, Jun 7, 2016 at 11:01 AM, Peter Burdine <pbur...@gmail.com 
> > wrote:
>
>> I just upgraded from 1.4.1 to 1.4.3 (running in cygwin).  When attempting 
>> to build a PDF, I am now getting:
>> ! LaTeX Error: File `iftex.sty' not found.
>>
>> I am assuming it is referring to 
>> https://www.ctan.org/tex-archive/macros/latex/contrib/iftex?lang=en.  Is 
>> this file supposed to be included with Sphinx now or do I have to tell all 
>> my users they have more configuration to do?
>>
>> Thanks,
>> Peter
>>
>> -- 
>> You received this message because you are subscribed to the Google Groups 
>> "sphinx-users" group.
>> To unsubscribe from this group and stop receiving emails from it, send an 
>> email to sphinx-users...@googlegroups.com .
>> To post to this group, send email to sphinx...@googlegroups.com 
>> .
>> Visit this group at https://groups.google.com/group/sphinx-users.
>> For more options, visit https://groups.google.com/d/optout.
>>
>
>

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

[sphinx-users] iftex.sty is required by not delivered with 1.4.3?

[Peter Burdine]

I just upgraded from 1.4.1 to 1.4.3 (running in cygwin).  When attempting 
to build a PDF, I am now getting:
! LaTeX Error: File `iftex.sty' not found.

I am assuming it is referring to 
https://www.ctan.org/tex-archive/macros/latex/contrib/iftex?lang=en.  Is 
this file supposed to be included with Sphinx now or do I have to tell all 
my users they have more configuration to do?

Thanks,
Peter

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

[sphinx-users] Re: parsed-literal/code-block and other preformated block in PDF Output

[Peter Burdine]

I think this is related to https://github.com/sphinx-doc/sphinx/issues/2167 
that Andrea put in last year.

On Saturday, May 14, 2016 at 10:27:47 AM UTC-7, Peter Burdine wrote:
>
> Is there a way to either completely enable or disable syntax-highlighting 
> for parsed-literal and code-blocks?  I am running into an issue where I 
> have to use parsed-literal directives because I need some formatting in 
> code blocks to show which words are variables, eg something like this:
>
> .. parsed-literal::
>
> # cd *someDirectory*
>
> In other places I used rst replacements like:
>
> .. parsed-literal::
> 
> # cd |directory|
>
> In the first example, in the PDF output it shows up like a normal code 
> block (black border, syntax highlighting, etc), but the second example 
> doesn't
>
> In the .tex file for the marked up parsed-literal it looks like:
> \begin{Verbatim}[commandchars=\\\{\}]
> ...content here...
> \end{Verbatim}
>
> But in the parsed-literal with the substitution, it renders like:
> \begin{alltt}
> ...content here...
> \end{alltt}
>
> The same thing happens in HTML output (though not as noticible).  The 
> marked up parsed-literal gets rendered with 'default-highlight' but the one 
> with the replacement gets rendered with 'literal-block'.
>
> Is there a way to force to do one or the other?  
>
>
>

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

[sphinx-users] Re: TOC Depth in HTML vs PDF -- PDF output has numbered headings up to level 3

[Peter Burdine]

I figured out that Sphinx defaults to 3 levels for PDF.  If you want more 
you need to include something like this in your preamble:

\setcounter{secnumdepth}{9}
>

On Saturday, May 14, 2016 at 3:31:52 PM UTC-7, Peter Burdine wrote:
>
> I'm trying to write a document using the 'manual' format.  In my main TOC, 
> I've tried setting :maxdepth: as high as 15, but in the PDF output it only 
> creates numbered headings for the first 3 levels.  All level 4 headings and 
> below are no longer numbered.  The heading in the HTML output are numbered 
> correctly.  Has anyone else run into something like this?
>
>

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

[sphinx-users] TOC Depth in HTML vs PDF -- PDF output has numbered headings up to level 3

[Peter Burdine]

I'm trying to write a document using the 'manual' format.  In my main TOC, 
I've tried setting :maxdepth: as high as 15, but in the PDF output it only 
creates numbered headings for the first 3 levels.  All level 4 headings and 
below are no longer numbered.  The heading in the HTML output are numbered 
correctly.  Has anyone else run into something like this?

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

[sphinx-users] parsed-literal/code-block and other preformated block in PDF Output

[Peter Burdine]

Is there a way to either completely enable or disable syntax-highlighting 
for parsed-literal and code-blocks?  I am running into an issue where I 
have to use parsed-literal directives because I need some formatting in 
code blocks to show which words are variables, eg something like this:

.. parsed-literal::

# cd *someDirectory*

In other places I used rst replacements like:

.. parsed-literal::

# cd |directory|

In the first example, in the PDF output it shows up like a normal code 
block (black border, syntax highlighting, etc), but the second example 
doesn't

In the .tex file for the marked up parsed-literal it looks like:
\begin{Verbatim}[commandchars=\\\{\}]
...content here...
\end{Verbatim}

But in the parsed-literal with the substitution, it renders like:
\begin{alltt}
...content here...
\end{alltt}

The same thing happens in HTML output (though not as noticible).  The 
marked up parsed-literal gets rendered with 'default-highlight' but the one 
with the replacement gets rendered with 'literal-block'.

Is there a way to force to do one or the other?  


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

[sphinx-users] Re: absolute path from Root to import image

[Peter Burdine]

I don't think this works.  See the thread here about documents outside of 
the "root" directory.

https://groups.google.com/d/msg/sphinx-users/7k6YJ7-t5BY/32h7NWegHgAJ 
"ImportError messages when running "make html" when the source files are 
located in a different folder than sphinx's"

--Peter

On Friday, May 6, 2016 at 4:25:34 PM UTC-7, fabien leboeuf wrote:
>
> Hi
>
>
> I would like to gather all my images in the same folder. ( media)  
>
>  
> how can i import an image in  my rst  
>
>
> I would like to use this kind of directive 
>
> .. image:: ROOT/media/image.png
>
> instead of using am relative path from my rst
>
> regards
>
> Fabien
>  
>

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

[sphinx-users] Re: ImportError messages when running "make html" when the source files are located in a different folder than sphinx's

[Peter Burdine]

I ran into the same issue.  The consensus I found was that it isn't 
supported.  If you run on UNIX-ish systems, you can use symlinks then it 
will be happy.  On Windows, you can kind of do the same thing,  
Unfortunately, you need admin rights to make links on Windows, but you 
don't need admin rights to make junctions.  So we created junctions under 
our source directory to point to the actual contents elsewhere on the file 
system.  For example, we have some common source that is shared between 
documents so our structure looks something like:
root 
  document1
...
source
  common   ->  ..\..\common
  document2

source
  common   ->  ..\..\common
  common
files_common_to_document1_document



The links would be created with the command "mklink /j common 
..\..\common".  Note that MS decided to reverse the parameters so they 
aren't compatible with UNIX.

Hope that helps.

--Peter


On Sunday, April 10, 2016 at 4:01:26 AM UTC-7, Sagiv Grupper wrote:
>
> Hi,
> I configured Sphinx in a dedicated folder (using sphinx-quickstart), on my 
> local machine - for example c:\Documentation.
> My python code is located in another folder for instance c:\dev
>
> I performed the following steps:
>
>1. From the Sphinx folder (Documentation), I ran: "sphinx-apidoc -o . 
>c:\dev" command in order to create .rst files.
>2. Then I ran "make html"
>
> I received lots of ImportError messages.
> Html files were created in the _build folder but they contained partial 
> data.
>
> I also tried to edit conf.py file (sys.path.insert(0, "c:\\dev")) but it 
> didn't help.
>
> The only way that I managed to generate the documentation, was when I 
> copied the source folder and located it under the Documentation folder.
>
> What can be the problem?
>
> Thanks for the help.
>
> Sagiv
>
>
>
>

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

[sphinx-users] Re: ImportError messages when running "make html" when the source files are located in a different folder than sphinx's

[Peter Burdine]

>From my research it doesn't appear that this works in Sphinx.  What you can 
do though is create links or junctions under your source directory to make 
it look like source files are in a subdirectory of your project.  That will 
allow Sphinx to consume them.  You have to have admin rights in Windows to 
make a link, but not a junction, so that may be your best bet.  Be aware 
though, that SVN doesn't support links/junctions on Windows, so if you use 
SVN, you need to be careful not to check in the junction.  Instead check in 
the directory where your source files are.  The command on windows is 
"mklink /j target source".  This is the method I used for common files on 
Windows systems.

On Sunday, April 10, 2016 at 4:01:26 AM UTC-7, Sagiv Grupper wrote:
>
> Hi,
> I configured Sphinx in a dedicated folder (using sphinx-quickstart), on my 
> local machine - for example c:\Documentation.
> My python code is located in another folder for instance c:\dev
>
> I performed the following steps:
>
>1. From the Sphinx folder (Documentation), I ran: "sphinx-apidoc -o . 
>c:\dev" command in order to create .rst files.
>2. Then I ran "make html"
>
> I received lots of ImportError messages.
> Html files were created in the _build folder but they contained partial 
> data.
>
> I also tried to edit conf.py file (sys.path.insert(0, "c:\\dev")) but it 
> didn't help.
>
> The only way that I managed to generate the documentation, was when I 
> copied the source folder and located it under the Documentation folder.
>
> What can be the problem?
>
> Thanks for the help.
>
> Sagiv
>
>
>
>

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

[sphinx-users] How can I get headers/footers on the title page in latexpdf output

[Peter Burdine]

How can I get headers/footers on the title page in latexpdf output?  I've 
been able to modify

   - \fancypagestyle{plain}
   - \fancypagestyle{normal}

to get the headers/footers of the rest of the pages working, but for the 
life of me, I can't get any headers/footers to show up on the title page.  
Can anyone provide some pointers as to how I could get it to work?


Thanks,

Peter

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