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

[Fiona Hanington]

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: Wiki based on Sphinx

[Ashwin Kumar]

Hi Vivian,

I'm interested in doing something similar too. Can you please share 
your wsgi application with me?

Thanks,
Ashwin

On Tuesday, March 15, 2011 at 7:55:03 AM UTC-7, Vivian De Smedt wrote:
>
> Dear All,
>
> We write our documentation using Sphinx.
> But some of us are abroad with no source control access and they would 
> like to edit the doc via their web browser.
> So I wanted to transform the static Sphinx set of pages into a wiki.
>
> Because it looked no so difficult I did it.
> Now I wondered if some others had the same desire and if so what are 
> solutions they found.
> Maybe could I reuse it and get something more sophisticated that what I 
> built (it is fairly basic).
>
> If someone is interested to the small wsgi application I built I'll be 
> glad to share it.
> And if you think it could be a valuable addition to Sphinx I'll be 
> delighted to give it to the project.
>
> Yours,
> Vivian.
>
>

-- 
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 = *:
>>>
>>> from shared.conf import restrictions
>>> from shared.conf import *
>>> part = "09-1076A-D"
>>>
>>> # General information about the project.
>>> project = u'Getting Started'
>>>
>>> # The version info for the project you're documenting, acts as 
>>> replacement for
>>> # |version| and |release|, also used in various other places throughout 
>>> the
>>> # built documents.
>>> #
>>> # The short X.Y version.
>>> version = '2.6'
>>> # The full version, including alpha/beta/rc tags.
>>> release = version
>>>
>>> 

Re: [sphinx-users] sphinx (python) pdf generator

[Minkai Li]

I have seen the latex commands ,But I can not solve the issue. How can I do 
?

在 2016年10月14日星期五 UTC+8上午3:37:50，gsavix写道：
>
> hi. you need explicity and specific use of latex commands todo this.
>
> --
> gilberto dos santos alves
> +55(11)9-8646-5049
> sao paulo - sp - brasil
>
>
>
>
>
> 2016-10-12 22:07 GMT-03:00 Minkai Li :
>
>> I use sphinx python documentation generator,Sphinx generates LaTeX files 
>> via 
>> make latex
>> , and then uses LaTeX to generate the PDF via 
>> xelatex
>> I am able to generate notes using the Sphinx directive 
>> .. note::  .. attention::
>> However, the notes 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?
>>
>>
>> -- 
>> 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: Cross referencing breaks for inherited objects imported and documented in a parent module

[André Anjos]

Somebody posted a reply on the referenced SO thread:

Apparently, the solution is to reset the value of `__module__` on the 
affected classes. So, in `a/__init__.py`, you can do the following to fix 
the issue:

```python
A.__module__ = __name__
B.__module__ = __name__
```

This seems to fix the problem for us. Isn't there some sort of `:alias:` 
command in Sphinx that could do something equivalent w/o this python hack?

Thanks, Andre

On Thursday, October 13, 2016 at 10:09:07 PM UTC+2, André Anjos wrote:
>
> I'm trying to get my Sphinx documentation build correctly and have 
> cross-references (including those from inherited relations) work right.
>
> In my project, I have a situation which is depicted in the example below, 
> which I replicated for convenience on [this github repo](
> https://github.com/anjos/sphinx-broken-xref):
>
> ```sh
> $ tree .
> .
> ├── a
> │   ├── b
> │   │   └── __init__.py
> │   └── __init__.py
> ├── conf.py
> ├── index.rst
> └── README.md
> ```
>
> In `a.b.__init__`, I declare classes `A` and `B`. `B` inherits from `A`. 
> In `a.__init__`, I import `A` and `B` like: `from .b import A, B`. The 
> reason I do this in my real projects is to reduce the import paths on 
> modules while keeping implementation of specific classes in separate files.
>
> Then, in my rst files, I *autodoc* module `a` with `.. automodule:: a`. 
> Because `a.b` is just an auxiliary module, I don't *autodoc* it since I 
> don't want to get repeated references to the same classes and not to 
> confuse the user on what they should be really doing. I also set 
> `show-inheritance` expecting `a.B` will have a back link to `a.A`.
>
> If I try to sphinx-build this in nit-picky mode, I'll get the following 
> warning:
>
> ```sh
> WARNING: py:class reference target not found: a.b.A
> ```
>
> If I look at the generated documentation for class `B`, then I verify it 
> is not properly linked against class `A`, which just confirms the warning 
> above. If I *autodoc* module `a.b` instead, it will work, but my 
> documentation will not show the shortcuts I intended when I wrote the 
> module.
>
> Is there a fix for this without *autodoc*'ing module `a.b`? I.e., keeping 
> the imports in the way they are?
>
> Thanks for any tip.
>
> [1] 
> http://stackoverflow.com/questions/40018681/sphinx-cross-referencing-breaks-for-inherited-objects-imported-and-documented-in
> [2] https://github.com/anjos/sphinx-broken-xref
> [3] https://github.com/sphinx-doc/sphinx/issues/3048
>

-- 
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.