Re: [sphinx-users] How to specify a link image URL header?

[Luc Saffre]

Thank you, this is indeed an interesting extension!
But it is not enough for me. It tells Facebook to specify a global link
image URL header for every page on my website.
That's nice, but I want to be able to say *on certain pages* that this
particular page has a custom link image URL.
I guess that I must say it either by a file-wide metadata field
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#file-wide-metadata>
or using a directive.
I will wait a few days before trying to write something myself, maybe
you get more ideas.

Luc

On 08.11.21 17:27, Komiya Takeshi wrote:
> How about https://pypi.org/project/sphinxext-opengraph/?
>
> 2021年11月8日(月) 13:04 Luc Saffre :
>> Hi all,
>>
>> when somebody shares, in a social media platform, a link to a website 
>> generated by Sphinx, the platform analyzes the content to find out a title 
>> and a picture for that link. Facebook for example looks for a link image URL 
>> header. If no such header is present, it probably looks for the first 
>> picture on the page, which is not necessarily what we want. How can we 
>> spcify an explicit link image url for a page?
>>
>> Luc
>>
>> --
>> 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/f0efdb12-1d0d-e68d-6ccd-5cbd1fcbfdbb%40gmail.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/5b31a061-10d0-a540-a94a-926562ba1dd3%40gmail.com.

[sphinx-users] How to specify a link image URL header?

[Luc Saffre]

Hi all,

when somebody shares, in a social media platform, a link to a website
generated by Sphinx, the platform analyzes the content to find out a
title and a picture for that link. Facebook for example looks for a link
image URL header
.
If no such header is present, it probably looks for the first picture on
the page, which is not necessarily what we want. How can we spcify an
explicit link image url for a page?

Luc

-- 
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/f0efdb12-1d0d-e68d-6ccd-5cbd1fcbfdbb%40gmail.com.

Re: [sphinx-users] ANN: Sphinx-4.1.0 is out

[Luc Saffre]

Now it works perfectly. Thanks for your work!
Luc

On 14.07.21 20:29, Komiya Takeshi wrote:
> Sorry for troubling on updating Sphinx. I just bumped Sphinx-4.1.1. It
> can be installed without dependency troubles.
>
> Thanks,
> Takeshi KOMIYA
>
> 2021年7月12日(月) 3:40 Luc Saffre :
>> After upgrading, I have the following traceback and in all my doctrees, and 
>> I have no idea why. Neither "epub3" nor "RemovedInSphinx40Warning" occur in 
>> any of my source files. Any hints?
>>
>> Luc
>>
>> Invoke sphinx-build -b html -T -d 
>> /home/luc/mypy/lino_local/jsvv/docs/.build/.doctrees -W --keep-going . 
>> /home/luc/mypy/lino_local/jsvv/docs/.build
>> Running Sphinx v4.1.0
>> loading translations [et]... done
>>
>> Traceback (most recent call last):
>>   File 
>> "/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/registry.py", 
>> line 429, in load_extension
>> mod = import_module(extname)
>>   File "/home/luc/virtualenvs/py3/lib/python3.6/importlib/__init__.py", line 
>> 126, in import_module
>> return _bootstrap._gcd_import(name[level:], package, level)
>>   File "", line 994, in _gcd_import
>>   File "", line 971, in _find_and_load
>>   File "", line 955, in _find_and_load_unlocked
>>   File "", line 665, in _load_unlocked
>>   File "", line 678, in exec_module
>>   File "", line 219, in 
>> _call_with_frames_removed
>>   File 
>> "/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/builders/epub3.py",
>>  line 18, in 
>> from sphinx.builders import _epub_base
>>   File 
>> "/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/builders/_epub_base.py",
>>  line 23, in 
>> from sphinx.builders.html import BuildInfo, StandaloneHTMLBuilder
>>   File 
>> "/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/builders/html/__init__.py",
>>  line 1288, in 
>> import sphinxcontrib.serializinghtml  # NOQA
>>   File 
>> "/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinxcontrib/serializinghtml/__init__.py",
>>  line 16, in 
>> from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
>> ImportError: cannot import name 'RemovedInSphinx40Warning'
>>
>> The above exception was the direct cause of the following exception:
>>
>> Traceback (most recent call last):
>>   File 
>> "/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/cmd/build.py", 
>> line 279, in build_main
>> args.tags, args.verbosity, args.jobs, args.keep_going)
>>   File 
>> "/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/application.py",
>>  line 233, in __init__
>> self.setup_extension(extension)
>>   File 
>> "/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/application.py",
>>  line 393, in setup_extension
>> self.registry.load_extension(self, extname)
>>   File 
>> "/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/registry.py", 
>> line 433, in load_extension
>> err) from err
>> sphinx.errors.ExtensionError: Could not import extension 
>> sphinx.builders.epub3 (exception: cannot import name 
>> 'RemovedInSphinx40Warning')
>>
>> Extension error:
>> Could not import extension sphinx.builders.epub3 (exception: cannot import 
>> name 'RemovedInSphinx40Warning')
>> C
>>
>>
>> On 11.07.21 20:29, Komiya Takeshi wrote:
>>
>> Hi all,
>>
>> Today, we released Sphinx-4.1.0. It contains many improvements and
>> bug fixes.
>>
>> For more detail, please check the CHANGES file:
>> https://github.com/sphinx-doc/sphinx/blob/4.1.x/CHANGES
>>
>> Enjoy documentation!
>>
>> Thanks,
>> Takeshi KOMIYA
>>
>>

-- 
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/36305fd5-7984-3c4d-b300-b913d99a28bc%40gmail.com.

Re: [sphinx-users] Re: ANN: Sphinx-4.1.0 is out

[Luc Saffre]

On 13.07.21 00:40, jfbu wrote:
> pip install -U sphinxcontrib.serializinghtml
>>
>> and perhaps same with sphinxcontrib.htmlhelp as I see I updated both
>> on June 13
>>

Yes, this fixed my problems. Great! Thanks!

Luc

-- 
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/45ca7f2c-bd3f-5334-538a-1ed63ec27913%40gmail.com.

Re: [sphinx-users] ANN: Sphinx-4.1.0 is out

[Luc Saffre]

After upgrading, I have the following traceback and in all my doctrees,
and I have no idea why. Neither "epub3" nor "RemovedInSphinx40Warning"
occur in any of my source files. Any hints?

Luc

Invoke sphinx-build -b html -T -d
/home/luc/mypy/lino_local/jsvv/docs/.build/.doctrees -W --keep-going .
/home/luc/mypy/lino_local/jsvv/docs/.build
Running Sphinx v4.1.0
loading translations [et]... done

Traceback (most recent call last):
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/registry.py",
line 429, in load_extension
    mod = import_module(extname)
  File "/home/luc/virtualenvs/py3/lib/python3.6/importlib/__init__.py",
line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "", line 994, in _gcd_import
  File "", line 971, in _find_and_load
  File "", line 955, in _find_and_load_unlocked
  File "", line 665, in _load_unlocked
  File "", line 678, in exec_module
  File "", line 219, in
_call_with_frames_removed
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/builders/epub3.py",
line 18, in 
    from sphinx.builders import _epub_base
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/builders/_epub_base.py",
line 23, in 
    from sphinx.builders.html import BuildInfo, StandaloneHTMLBuilder
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/builders/html/__init__.py",
line 1288, in 
    import sphinxcontrib.serializinghtml  # NOQA
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinxcontrib/serializinghtml/__init__.py",
line 16, in 
    from sphinx.deprecation import RemovedInSphinx40Warning,
deprecated_alias
ImportError: cannot import name 'RemovedInSphinx40Warning'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/cmd/build.py",
line 279, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/application.py",
line 233, in __init__
    self.setup_extension(extension)
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/application.py",
line 393, in setup_extension
    self.registry.load_extension(self, extname)
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/registry.py",
line 433, in load_extension
    err) from err
sphinx.errors.ExtensionError: Could not import extension
sphinx.builders.epub3 (exception: cannot import name
'RemovedInSphinx40Warning')

Extension error:
Could not import extension sphinx.builders.epub3 (exception: cannot
import name 'RemovedInSphinx40Warning')
C


On 11.07.21 20:29, Komiya Takeshi wrote:
> Hi all,
>
> Today, we released Sphinx-4.1.0. It contains many improvements and
> bug fixes.
>
> For more detail, please check the CHANGES file:
> https://github.com/sphinx-doc/sphinx/blob/4.1.x/CHANGES
>
> Enjoy documentation!
>
> Thanks,
> Takeshi KOMIYA
>

-- 
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/11aad95f-ddaa-b9a9-a701-8063b9cd8dcb%40gmail.com.

Re: [sphinx-users] Unable to get intended document organisation

[Luc Saffre]

I added my approval to PR https://github.com/sphinx-doc/sphinx/pull/3622

I had a look at the code changes. They make sense to me. I realize that
this is probably difficult to cover by any test. Difficult to estimate
whether this might disturb other users. But as the maintainer of more
than 30 Sphinx websites I can say that if this change really would turn
out to have unexpected side effects on one of my sites, I wouldn't get
angry with the Sphinx team and actually even praise them for having
jumped into this.

Luc

On 26.05.21 00:52, Sidney Cadot wrote:
> This PR seems to address this very
> issue: https://github.com/sphinx-doc/sphinx/pull/3622
>
> But it somehow still in review after 3 or 4 years...
> On Tuesday, May 25, 2021 at 8:52:02 AM UTC+2 Sidney Cadot wrote:
>
> Hi Luc,
>
> As an example, this is a page of a project I am working on:
>
>     https://pydwf.readthedocs.io/en/latest/pydwf_api/DwfLibrary.html
>
> This page talks about a certain class in broad terms, then dives
> into details on some sub-topics in pages that follow. In the ToC I
> want those sub-topics one hierarchical level below the
> introductory section. I want both the intro and the sub-topics on
> their own pages.
>
> Currently I do this by a hack: not having headings in the
> intro-page. I now use ::rubrics in the intro page, and a hidden
> ToC at the end of the intro page. That gives me the ToC structure
> I want, at the cost of being unable to use any headings on the
> intro page. The use of ::rubric's is a way to avoid that.
>
> I could also do this -- every line a separate rst page. I think
> this is what you suggest:
>
> * ToC superpage
>     * Overview section B with headings and all.
>     * Detailed section B1
>     * Detailed section B2
>
> However, this is not what I want. The sections B, B1, and B2 are
> at the same hierarchical level here (I want B1 and B2 below B in
> the ToC); and a ToC superpage will be generated that I really
> don't want, either in HTML or in in PDF. 
>
> > It's more intuitive for the reader when every page is *either* a
> node of the ToC *or* a content page with sections.
>
> I don't agree in general. There are many fine educational books
> and manuals that do what I try to achieve. Let's agree to disagree
> on this and discuss if/how it could be done.
>
> I would like to ask the inverse question; suppose you /have/ a
> page with both headings and a ToC. I don't see any case where  the
> useful thing would be to add the ToC at the level determined by
> the level where the ::toctree happens to sit in the first page.
> Suppose the text preceding the ::toctree happens to end at
> subheading-level 3, the ToC entries will be inserted one level
> below that, which is undesirable in any situation I can think of.
>
> Having googled for this issue a quite a bit prior to asking here,
> I have seen that I am not the only one who was surprised by this.
> Only when I started experimenting with a small project to figure
> out what was going on, I started understanding what Sphinx is doing.
>
> You end up with webpages recommending not to mix headings and
> ::toctree directives on the same page at all
> (eg 
> https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/MenuHierarchy.html),
> without going into detail on the /why/, or if it is even sensible
> to have to recommend such a policy. If in-page headings and
> toctrees don't mix, then I feel it would be better to emit an
> error and refuse to render, than to have the current behaviour
> where the toctree items are inserted one level below whatever
> happens to be the heading level where the toctree resides.
>
> Best, Sidney
>
>
>
>
>
> On Tuesday, May 25, 2021 at 7:40:19 AM UTC+2 Luc Saffre wrote:
>
> Yes, understandable. What I don't understand: why do you need
> the structure you are asking for? Can you give us a real-world
> example for your tree structure? Why don't you simply move the
> three sections from B into a separate page B0? It's more
> intuitive for the reader when every page is *either* a node of
> the ToC *or* a content page with sections. A third type of
> page is where you have section titles and each section
> contains a toctree (I use this when I have a toctree node with
> many entries but do not (yet) want to move them to separate
> toctree pages.
>
> Luc
>
>
> On 25.05.21 00:30, Sidney Cadot wrote:
>> Hi Luc,
>>
>>

Re: [sphinx-users] Unable to get intended document organisation

[Luc Saffre]

Yes, understandable. What I don't understand: why do you need the
structure you are asking for? Can you give us a real-world example for
your tree structure? Why don't you simply move the three sections from B
into a separate page B0? It's more intuitive for the reader when every
page is *either* a node of the ToC *or* a content page with sections. A
third type of page is where you have section titles and each section
contains a toctree (I use this when I have a toctree node with many
entries but do not (yet) want to move them to separate toctree pages.

Luc

On 25.05.21 00:30, Sidney Cadot wrote:
> Hi Luc,
>
> Thanks for the suggestion!
>
> The problem with a normal*..include* directive will be that I lose the
> separate pages for B1 and B2 in the HTML backend (and other backends
> that don't combine everything).
>
> When I wrote "I want to keep the 7 documents", what I meant to say is
> not so much that I want to hold on to the separate source documents; I
> want to make sure that individual HTML pages are generated for each of
> the 7 documents. The /include/ approach//doesn't accomplish that.
>
> Cheers, Sidney
>
> On Monday, May 24, 2021 at 10:11:38 PM UTC+2 Luc Saffre wrote:
>
> Did you try to .. include:: the two docs B1 and B2? In that case
> you must also use the exclude_patterns
> 
> <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns>
> config option to tell Sphinx to exclude them from the build.
>
> Luc
>
>
> On 24.05.21 20:52, Sidney Cadot wrote:
>>
>> Hi all,
>>
>> I am having trouble getting sphinx to do what I want.
>>
>> I have 7 documents: index, A, A1, A2 ; B, B1, B2.
>>
>> The index has a toctree that lists A and B.
>> Document A has a toctree that lists A1 and A2.
>> Document B has three sections followed by a toctree that lists B1
>> and B2.
>>
>> This results in the ToC that I have attached as a picture.
>>
>> What I would like is that Document B1 and B2 are listed in the
>> ToC at the same level as the subsections of document B. In
>> effect, I want the ToC entries {B1, B2} to be direct children of
>> Document B, just like {A1, A2} are direct children of A.
>>
>> I want to keep the 7 documents; and I want to keep everything in
>> the order as stated.
>>
>> Is this possible? Or does the Sphinx parser and/or internal
>> document datastructure not allow this for some reason?
>>
>> Kind regards,
>>   Sidney
>> -- 
>> 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 view this discussion on the web visit
>> 
>> https://groups.google.com/d/msgid/sphinx-users/976e3827-35b5-4e72-ac1f-7e29da91f49bn%40googlegroups.com
>> 
>> <https://groups.google.com/d/msgid/sphinx-users/976e3827-35b5-4e72-ac1f-7e29da91f49bn%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
> <mailto:sphinx-users+unsubscr...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/sphinx-users/4cfa2a5e-7b16-4ab6-9a1b-2729da549804n%40googlegroups.com
> <https://groups.google.com/d/msgid/sphinx-users/4cfa2a5e-7b16-4ab6-9a1b-2729da549804n%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/02102cf5-ab77-d7f8-d6cc-af95fd62ceab%40gmail.com.

Re: [sphinx-users] Unable to get intended document organisation

[Luc Saffre]

Did you try to .. include:: the two docs B1 and B2? In that case you
must also use the exclude_patterns

config option to tell Sphinx to exclude them from the build.

Luc

On 24.05.21 20:52, Sidney Cadot wrote:
>
> Hi all,
>
> I am having trouble getting sphinx to do what I want.
>
> I have 7 documents: index, A, A1, A2 ; B, B1, B2.
>
> The index has a toctree that lists A and B.
> Document A has a toctree that lists A1 and A2.
> Document B has three sections followed by a toctree that lists B1 and B2.
>
> This results in the ToC that I have attached as a picture.
>
> What I would like is that Document B1 and B2 are listed in the ToC at
> the same level as the subsections of document B. In effect, I want the
> ToC entries {B1, B2} to be direct children of Document B, just like
> {A1, A2} are direct children of A.
>
> I want to keep the 7 documents; and I want to keep everything in the
> order as stated.
>
> Is this possible? Or does the Sphinx parser and/or internal document
> datastructure not allow this for some reason?
>
> Kind regards,
>   Sidney
> -- 
> 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/976e3827-35b5-4e72-ac1f-7e29da91f49bn%40googlegroups.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/3a270671-666f-e31b-0c9e-2420ecbf3641%40gmail.com.

Re: [sphinx-users] Sphinx-4.0.0 is out

[Luc Saffre]

Congratulations and thanks for your ongoing work!

(I cannot yet give more feedback because I use sphinx-panels, which does
not yet work with Sphinx 4. I hope that they will work on it soon.)

Luc

On 09.05.21 06:30, Komiya Takeshi wrote:
> Hi all,
>
> I'm delighted to announce the release of Sphinx 4.0.0 final, now available on
> the Python package index at .
>
> It includes many changes including incompatible ones.
> Please confirm it working fine on your documents.
>
> In detail, please see CHANGES:
> https://github.com/sphinx-doc/sphinx/blob/4.0.x/CHANGES
>
> Thanks to all collaborators and contributers!
>
> What is it?
> ===
>
> Sphinx is a tool that makes it easy to create intelligent and beautiful
> documentation for Python projects (or other documents consisting of
> multiple reStructuredText source files).
>
> Website: http://sphinx-doc.org/
>
> Enjoy!
>

-- 
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/ec162ac4-816a-528d-3087-50962ea28303%40gmail.com.

Re: [sphinx-users] Re: Numbered paragraphs

[Luc Saffre]

Yes, in a first phase I will indeed just want html output. Sorry for not
having mentioned it in my original post.

Luc

On 27.02.21 13:58, jfbu wrote:
> Hi again,
>
> only now I realize the question was not only for pdf output via make
> latexpdf
>
>
> sorry, but as the first linked document was a PDF, I focused on that
>
>
> obviously you don't want to do what I suggest if also targeting other
> outputs
>
>
> then you should probably hook via a Sphinx extension into the
> "paragraph" nodes,
>
>
> hope someone more competent than me can intervene here,
>
> Best
>
> Jean-François
>
>
> Le 27/02/2021 à 11:31, Luc Saffre a écrit :
>> Hi
>>
>> I would like to migrate a series of documents from LibreOffice to
>> Sphinx. Here is an example (it's in German, but watch the paragraph
>> numbering and headings):
>>
>> https://saffre-rumma.net/dl/Software-Wartungsvertrag.pdf
>>
>> I cannot migrate these documents because I didn't yet manage to
>> implement this style of continuous paragraph numbering.
>> This style is used by other author as well. Here is an example:
>>
>> http://www.vatican.va/content/francesco/en/encyclicals/documents/papa-francesco_20201003_enciclica-fratelli-tutti.html
>>
>>
>> How would I do this in Sphinx?
>> I definitively do not want to number the paragraphs manually.
>> The only idea I had so far is to define a directive and a role like
>> this:
>>
>> .. step:: x
>>    :value: 1
>>    :style: ({})
>>
>> Title
>> =
>>
>> :step:`x` first paragraph blabla
>>
>> Section heading
>> ---
>>
>> :step:`x` second paragraph blabla
>>
>>
>> Does anybody do something similar? I didn't yet implement my idea
>> because I'd prefer to join some existing effort rather than
>> reinventing the wheel.
>>
>> Luc
>>
>> -- 
>> 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
>> <mailto:sphinx-users+unsubscr...@googlegroups.com>.
>> To view this discussion on the web visit
>> https://groups.google.com/d/msgid/sphinx-users/c18622fa-ce62-3a2f-e8de-4f6a7820cdf6%40gmail.com
>> <https://groups.google.com/d/msgid/sphinx-users/c18622fa-ce62-3a2f-e8de-4f6a7820cdf6%40gmail.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/5e4b4aae-eb0b-f0f7-740a-81bbc4cb6022%40gmail.com.

[sphinx-users] Numbered paragraphs

[Luc Saffre]

Hi

I would like to migrate a series of documents from LibreOffice to
Sphinx. Here is an example (it's in German, but watch the paragraph
numbering and headings):

https://saffre-rumma.net/dl/Software-Wartungsvertrag.pdf

I cannot migrate these documents because I didn't yet manage to
implement this style of continuous paragraph numbering.
This style is used by other author as well. Here is an example:

http://www.vatican.va/content/francesco/en/encyclicals/documents/papa-francesco_20201003_enciclica-fratelli-tutti.html

How would I do this in Sphinx? 
I definitively do not want to number the paragraphs manually.
The only idea I had so far is to define a directive and a role like this:

.. step:: x
  :value: 1
  :style: ({})

Title
=

:step:`x` first paragraph blabla

Section heading
---

:step:`x` second paragraph blabla


Does anybody do something similar? I didn't yet implement my idea
because I'd prefer to join some existing effort rather than reinventing
the wheel.

Luc

-- 
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/c18622fa-ce62-3a2f-e8de-4f6a7820cdf6%40gmail.com.

Re: [sphinx-users] Sorting modules for doctest

[Luc Saffre]

I use an external tool (atelier, written by myself) to run doctest on
every document of my Sphinx doctrees. It sorts the docs alphabetically
to avoid such surprises:

https://www.lino-framework.org/dev/doctests.html

IOW, create a subdirectory "tests" next to your docs directory, create a
file test_docs.py in that directory as described, then run "pip install
atelier" and "python -m unittest discover -s tests".

hth
Luc

On 17.02.21 23:46, Zach R wrote:
> Hello!
>
> Love Sphinx and have been using it for years.
>
> One thing that I've never managed to get set up is to have the
> doctests all done in a deterministic (preferably alphabetic) order
> when run with "sphinx -b doctest"
>
> Is there any way to do this easily?
>
> Thanks!
> Zach
> -- 
> 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/25b1d333-f060-4dc0-ad53-f61fc73784a8n%40googlegroups.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/7b82ffe7-a81f-56ef-1269-e05625766e77%40gmail.com.

Re: [sphinx-users] ANN: Sphinx-3.5.0 is out

[Luc Saffre]

Thanks again for your continued work!

I had a problem after upgrading. Probably some silly detail, but I
couldn't yet find the explanation because the warning mesage doesn't
really help me. So I opened an issue:
https://github.com/sphinx-doc/sphinx/issues/8882

Luc

On 14.02.21 10:16, Komiya Takeshi wrote:
> Hi all,
>
> Today, I released Sphinx-3.5.0. It contains many improvements and
> bug fixes.
>
> For more detail, please check the CHANGES file:
> https://github.com/sphinx-doc/sphinx/blob/3.5.x/CHANGES
>
> Enjoy documentation!
>
> Thanks,
> Takeshi KOMIYA
>

-- 
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/7ebc3437-21a9-6f87-49e6-2ebd66e5eb26%40gmail.com.

Re: [sphinx-users] how to clean deleted strings from .po files

[Luc Saffre]

I use poedit to do that. Open the file with poedit and then select
"Catalog --> Purge deleted translations" from the menu.

Luc

On 03.02.21 18:57, Pieter Claeys wrote:
> I have written a quite large document using sphinx, and underwent
> several iterations with external translators. The translation workflow
> works fine, however I noticed that when I delete phrases/content in
> the .rst  source files, then there still always remains a 'MsgId'
> recording in the .po files.  
> I would like to clean these 'ghost' records from the .po files, to
> avoid running into unneeded translation costs.
>
> Is there a way to solve this? Can sphinx-intl be instructed to remove
> entries from the .po files for when the msgId is no longer present in
> the .pot file?
> -- 
> 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/b6a7a409-96c4-4a3b-9e74-23582ff53d1cn%40googlegroups.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/3707e313-187f-f97e-35d9-8ead19a7efb1%40gmail.com.

Re: [sphinx-users] Sphinx yaml to html

[Luc Saffre]

Yes.

On 10.12.20 14:44, ishan saxena wrote:
> Hi, 
>
> Is it possible to read a yaml file and convert that into 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 view this discussion on the web visit
> https://groups.google.com/d/msgid/sphinx-users/f2e44afb-8849-4ec6-abc9-3bfd8f75b9ccn%40googlegroups.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/d4b6ee4a-654e-93d8-818c-d028bf9e5480%40gmail.com.

Re: [sphinx-users] How to create ad hoc HTML anchors?

[Luc Saffre]

Looks as if you want the glossary directive (and the term role):
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-glossary

Luc

On 08.12.20 02:07, Pete wrote:
> What I want to do is write the .rst code for this HTML output:
>
> instead of:    energy
> it has to be:  energy
>
> How is this done?  The .rst code I'm using now is:   **energy**
>
> This will be used hundreds of times (using a software program to
> convert source into .rst files) in a multipage document (~150 .rst
> files) so a simple reference label approach, such as `.. _energy:` 
> would likely be created on different pages, generating
> multiply-defined errors.
>
> BTW, the word "energy" is just an example of the type of words that
> word be anchored.
>
> related topics:
> * https://groups.google.com/g/sphinx-dev/c/bNW2Tc4hhOA
>
> -- 
> 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/57d82d37-a9e3-416d-9c3e-b89e14784b03n%40googlegroups.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/605d699f-d9de-cdc7-27d6-d675ebe18d9a%40gmail.com.

Re: [sphinx-users] Make the heading levels of (sub)documents automatically dependent of the depth's levels of the folders they belong to

[Luc Saffre]

On 02.12.20 11:26, Denis Bitouzé wrote:
> But, meanwhile, do you see any way to temporarily active the feature
> I'm requesting? 

No, sorry, I have no idea where to start with such a feature. I'm afraid
that it isn't a quick win. But I don't know enough about the inner life
of Sphinx, so my feeling isn't actually relevant.

Luc

-- 
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/44496b25-a438-6f96-0339-76988e768689%40gmail.com.

Re: [sphinx-users] Make the heading levels of (sub)documents automatically dependent of the depth's levels of the folders they belong to

[Luc Saffre]

Interesting idea.
This should be clearly optional because there are doctrees that rely
precisely on the feature of having the logical structure independent
from file system structure.
Luc

On 01.12.20 22:07, Denis Bitouzé wrote:
>
> Hi,
>
> Suppose I have:
>
> - a `foo0.rst` file at the root (`source`) of my `sphinx-doc` source
> folder,
> - a `foo1.rst` file in a subfolder `subfolder1` of `source`,
> - a `foo2.rst` file in a subfolder `subfolder2` of `subfolder1`,
>
> that is:
>
>   ┌
>   │ $ tree source
>   │ source
>   │ ├── foo0.rst
>   │ └── subfolder1
>   │ ├── foo1.rst
>   │ └── subfolder2
>   │ └── foo2.rst
>   └
>
> all with the same content:
>
>   ┌
>   │ This a title
>   │ 
>   └
>
> Now, if the `index.rst` contains:
>     
>   ┌
>   │ Welcome to Test's documentation!
>   │ 
>   │
>   │ .. toctree::
>   │    :maxdepth: 3
>   │    :caption: Contents:
>   │
>   │    foo0
>   │    subfolder1/foo1
>   │    subfolder1/subfolder2/foo2
>   └
>
> `make html` gives:
>
>   ┌
>   │ Welcome to Test’s documentation!
>   │
>   │ Contents:
>   │
>   │ • This a title
>   │ • This a title
>   │ • This a title
>   └
>
> that is all the headings are sections.
>
> What I would like to get instead is the following:
>
>   ┌
>   │ Welcome to Test’s documentation!
>   │
>   │ Contents:
>   │
>   │ • This a title
>   │   ◦ This a title
>   │ ▪ This a title
>   └
>
> that is the heading of:
>
> - `foo0.rst` being a section,
> - `subfolder1/foo1.rst` being a subsection (and not a section),
> - `subfolder1/subfolder2/foo2.rst` being a subsubsection (and not
>   a section).
>
> My question is therefore: is it possible to make the heading levels of
> documents belonging to (sub(sub(...)))folders automatically depending on
> the depth's levels of the folders they belong to?
>
> Thanks.
> -- 
> Denis --
> 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/3e00313f-3985-48b6-9c09-592daa0922b6n%40googlegroups.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/545fe5fc-8379-c0b5-2311-a21f08af46d7%40gmail.com.

Re: [sphinx-users] Space Between Italic and Literal Words

[Luc Saffre]

By adding a backslash (\) before the space::

  *prefix*\ ``/lib``

Luc

On 07.11.20 13:53, bradley...@gmail.com wrote:
> Using rst how does one avoid a space between an italic word and a
> literal word ?
>
> The attached rst file demonstrates the problem:
> -- 
> 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/b8f5c22a-7077-40c4-aeda-baa2ab31fe66n%40googlegroups.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/85f22cbb-1705-4d82-6883-bc73fb5ef127%40gmail.com.

Re: [sphinx-users] autodoc reports errors for dict module variable

[Luc Saffre]

At least one good thing: I learned about the "#:" feature (i.e. the
possibility to add documentation without actually defining a docstring).

At the moment I have no more quick idea. And -forgive me- I prefer to
not dive deeper into this, I have so many other important things to do...

Luc

On 15.10.20 10:28, Andrew Porter wrote:
> Thanks Luc. I discovered the "#:" on
> https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
> (under autoattribute). Adding a docstring on the line immediately
> after the colour map makes no difference sadly :-( In case it helps,
> the rst generated by autodoc contains:
>
>     - :py:data:`SCHEDULE_COLOUR_MAP`
>
>     .. autodata:: SCHEDULE_COLOUR_MAP
>    :annotation:
>
>    .. code-block:: text
>
>   {'Assignment': 'blue',
>    'BuiltIn': 'magenta',
>    }
>
> Thanks,
>
> Andy.
> On Wednesday, 14 October 2020 at 19:45:17 UTC+1 Luc Saffre wrote:
>
> Okay...  I think i can confirm your assumption that autodoc is
> trying to render the docstring of the dict class object:
>
> >>> print(dict.__doc__)
> dict() -> new empty dictionary
> dict(mapping) -> new dictionary initialized from a mapping object's
>     (key, value) pairs
> dict(iterable) -> new dictionary initialized as if via:
>     d = {}
>     for k, v in iterable:
>     d[k] = v
> dict(**kwargs) -> new dictionary initialized with the name=value pairs
>     in the keyword argument list.  For example:  dict(one=1, two=2)
>
> Next idea: What is this "#:" syntax for specifying docstring?
> Seems that I missed some recent evolution of the Python language?
> What happens when you specify your docstring using the classical way:
>
>
>     SCHEDULE_COLOUR_MAP = {"Schedule": "white",
>    "Loop": "red",
>    "GlobalSum": "cyan"}
>     "Colour map to use when writing Invoke schedule to terminal."
>
> Luc
>
>
>
> On 14.10.20 16:57, Andrew Porter wrote:
>> Thanks Luc. I tried adding:
>>
>>     autodoc_inherit_docstrings = False
>>
>> to my conf.py, wiping all generated rst files and documentation
>> and building again but to no avail - I still get the same
>> warnings :-(
>>
>> Thanks,
>>
>> Andy
>>
>>  
>>  
>> On Wednesday, 14 October 2020 at 12:48:20 UTC+1 Luc Saffre wrote:
>>
>> Try setting autodoc_inherit_docstrings
>> 
>> <https://www.sphinx-doc.org/es/master/usage/extensions/autodoc.html#confval-autodoc_inherit_docstrings>
>> to False.
>>
>> Luc
>>
>>
>> On 14.10.20 10:36, Andrew Porter wrote:
>>> Hello,
>>>
>>> I'm using autodoc in Sphinx 3.2.1 and have a problem where
>>> it reports formatting errors from what I think is the `dict`
>>> docstring rather than my code. I have a module (`node`)
>>> which contains a dict:
>>>
>>>     #: Colour map to use when writing Invoke schedule to
>>> terminal.
>>>     SCHEDULE_COLOUR_MAP = {"Schedule": "white",
>>>    "Loop": "red",
>>>    "GlobalSum": "cyan"}
>>>
>>> This module is then made available in the __all__ list of
>>> the __init__.py of the package
>>> containing the module, i.e. I have an __init__.py that contains:
>>>
>>>     from nodes.node import SCHEDULE_COLOUR_MAP
>>>     __all__ = ['SCHEDULE_COLOUR_MAP']
>>>    
>>> When running Sphinx autodoc I see:
>>>
>>>     /blah blah/nodes/__init__.py:docstring of
>>> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:3: WARNING:
>>> Unexpected indentation.
>>>     /blah blah/nodes/__init__.py:docstring of
>>> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:4: WARNING: Block
>>> quote ends without a blank line; unexpected unindent.
>>>     /blah blah/nodes/__init__.py:docstring of
>>> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:7: WARNING:
>>> Unexpected indentation.
>>>     /blah blah/psyir/nodes/__init__.py:docstring of
>>> psyclone.psyir.nodes.SCHEDULE_

Re: [sphinx-users] autodoc reports errors for dict module variable

[Luc Saffre]

Okay...  I think i can confirm your assumption that autodoc is trying to
render the docstring of the dict class object:

>>> print(dict.__doc__)
dict() -> new empty dictionary
dict(mapping) -> new dictionary initialized from a mapping object's
    (key, value) pairs
dict(iterable) -> new dictionary initialized as if via:
    d = {}
    for k, v in iterable:
    d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs
    in the keyword argument list.  For example:  dict(one=1, two=2)

Next idea: What is this "#:" syntax for specifying docstring? Seems that
I missed some recent evolution of the Python language? What happens when
you specify your docstring using the classical way:

    SCHEDULE_COLOUR_MAP = {"Schedule": "white",
   "Loop": "red",
   "GlobalSum": "cyan"}
    "Colour map to use when writing Invoke schedule to terminal."

Luc


On 14.10.20 16:57, Andrew Porter wrote:
> Thanks Luc. I tried adding:
>
>     autodoc_inherit_docstrings = False
>
> to my conf.py, wiping all generated rst files and documentation and
> building again but to no avail - I still get the same warnings :-(
>
> Thanks,
>
> Andy
>
>  
>  
> On Wednesday, 14 October 2020 at 12:48:20 UTC+1 Luc Saffre wrote:
>
> Try setting autodoc_inherit_docstrings
> 
> <https://www.sphinx-doc.org/es/master/usage/extensions/autodoc.html#confval-autodoc_inherit_docstrings>
> to False.
>
> Luc
>
>
> On 14.10.20 10:36, Andrew Porter wrote:
>> Hello,
>>
>> I'm using autodoc in Sphinx 3.2.1 and have a problem where it
>> reports formatting errors from what I think is the `dict`
>> docstring rather than my code. I have a module (`node`) which
>> contains a dict:
>>
>>     #: Colour map to use when writing Invoke schedule to terminal.
>>     SCHEDULE_COLOUR_MAP = {"Schedule": "white",
>>    "Loop": "red",
>>    "GlobalSum": "cyan"}
>>
>> This module is then made available in the __all__ list of the
>> __init__.py of the package
>> containing the module, i.e. I have an __init__.py that contains:
>>
>>     from nodes.node import SCHEDULE_COLOUR_MAP
>>     __all__ = ['SCHEDULE_COLOUR_MAP']
>>    
>> When running Sphinx autodoc I see:
>>
>>     /blah blah/nodes/__init__.py:docstring of
>> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:3: WARNING: Unexpected
>> indentation.
>>     /blah blah/nodes/__init__.py:docstring of
>> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:4: WARNING: Block quote
>> ends without a blank line; unexpected unindent.
>>     /blah blah/nodes/__init__.py:docstring of
>> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:7: WARNING: Unexpected
>> indentation.
>>     /blah blah/psyir/nodes/__init__.py:docstring of
>> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:9: WARNING: Inline
>> strong start-string without end-string.
>>
>> As you can see, I've tried explicitly adding a docstring for the
>> dict using the `#:` markup but that doesn't seem to get picked up.
>>
>> I get exactly the same problem with a different dictionary in a
>> different module.
>>
>> Am I doing something wrong here?
>>
>> (FYI, you can reproduce this problem by cloning
>> https://github.com/stfc/PSyclone.git, cd PSyclone; pip install .;
>> cd doc/reference_guide; make html)
>>
>> Many thanks,
>>
>> Andy.
>> -- 
>> 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 view this discussion on the web visit
>> 
>> https://groups.google.com/d/msgid/sphinx-users/d845e746-db09-4712-ad82-058d34d591efn%40googlegroups.com
>> 
>> <https://groups.google.com/d/msgid/sphinx-users/d845e746-db09-4712-ad82-058d34d591efn%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
> <mailto:sphinx-users+unsubscr...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/sphinx-users/69bf03b2-9ae1-4023-9674-11a6b3c6f069n%40googlegroups.com
> <https://groups.google.com/d/msgid/sphinx-users/69bf03b2-9ae1-4023-9674-11a6b3c6f069n%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/4577ee9b-d975-987e-7d50-ad0cd5282ac7%40gmail.com.

Re: [sphinx-users] autodoc reports errors for dict module variable

[Luc Saffre]

Try setting autodoc_inherit_docstrings

to False.

Luc

On 14.10.20 10:36, Andrew Porter wrote:
> Hello,
>
> I'm using autodoc in Sphinx 3.2.1 and have a problem where it reports
> formatting errors from what I think is the `dict` docstring rather
> than my code. I have a module (`node`) which contains a dict:
>
>     #: Colour map to use when writing Invoke schedule to terminal.
>     SCHEDULE_COLOUR_MAP = {"Schedule": "white",
>    "Loop": "red",
>    "GlobalSum": "cyan"}
>
> This module is then made available in the __all__ list of the
> __init__.py of the package
> containing the module, i.e. I have an __init__.py that contains:
>
>     from nodes.node import SCHEDULE_COLOUR_MAP
>     __all__ = ['SCHEDULE_COLOUR_MAP']
>    
> When running Sphinx autodoc I see:
>
>     /blah blah/nodes/__init__.py:docstring of
> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:3: WARNING: Unexpected
> indentation.
>     /blah blah/nodes/__init__.py:docstring of
> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:4: WARNING: Block quote ends
> without a blank line; unexpected unindent.
>     /blah blah/nodes/__init__.py:docstring of
> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:7: WARNING: Unexpected
> indentation.
>     /blah blah/psyir/nodes/__init__.py:docstring of
> psyclone.psyir.nodes.SCHEDULE_COLOUR_MAP:9: WARNING: Inline strong
> start-string without end-string.
>
> As you can see, I've tried explicitly adding a docstring for the dict
> using the `#:` markup but that doesn't seem to get picked up.
>
> I get exactly the same problem with a different dictionary in a
> different module.
>
> Am I doing something wrong here?
>
> (FYI, you can reproduce this problem by cloning
> https://github.com/stfc/PSyclone.git, cd PSyclone; pip install .; cd
> doc/reference_guide; make html)
>
> Many thanks,
>
> Andy.
> -- 
> 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/d845e746-db09-4712-ad82-058d34d591efn%40googlegroups.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/4e2f40b0-fcf2-58bd-8186-984e243830e6%40gmail.com.

Re: [sphinx-users] sphinx-testing: Call for maintainers

[Luc Saffre]

Deprecation sounds a good plan. I don't see any reason to have a
duplicate test suite. Or are there still cases that would need to get
integrated?

Luc

On 03.10.20 15:30, Komiya Takeshi wrote:
> Hi,
>
> Since 1.6, we migrated to pytest and integarted the testing package to
> sphinx-core as sphinx.testing. As a result, sphinx-testing package has
> been no longer maintained for a long time. Additionally, nose project
> has also been not maintained now (the latest release is in 5 years
> ago!). So I'm thinking about the deprecation of the package.
>
> Before the deprecation action, I call for maintainers of
> sphinx-testing package. If nobody raise a hand, I'll deprecate the
> package soon.
>
> Thanks,
> Takeshi KOMIYA
>

-- 
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/b115981d-181b-4101-001a-3ee93e722a96%40gmail.com.

Re: [sphinx-users] ANN: New Sphinx theme: insipid

[Luc Saffre]

On 25.08.20 11:29, Matthias Geier wrote:
> If you find any other problems, please let me know!

One minor problem : the links to previous and next page are too big for
my taste. Also the general docs title is a bit too big. (I guess that I
can customize the relevant css, but if you agree with me, you maybe want
to change the default size)

Luc

-- 
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/412c0da3-c038-664c-ddc1-0c83635d681c%40gmail.com.

Re: [sphinx-users] ANN: New Sphinx theme: insipid

[Luc Saffre]

Great work! Thanks for sharing here.

I now switched to this theme for one of my private sites
https://hw.saffre-rumma.net/

Luc

PS After installing it as instructed, I had the following traceback. But
it went away after saying "pip install -U jinja2" (i.e. i had some older
version of jinja, sphinx_rtd_theme had no problems with that, but
insipid had)

Traceback (most recent call last):
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/cmd/build.py",
line 279, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/application.py",
line 277, in __init__
    self._init_builder()
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/application.py",
line 332, in _init_builder
    self.builder.init()
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/builders/html/__init__.py",
line 219, in init
    self.init_templates()
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/builders/html/__init__.py",
line 262, in init_templates
    self.templates.init(self, self.theme)
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/jinja2glue.py",
line 174, in init
    self.loaders = [SphinxFileSystemLoader(x) for x in loaderchain]
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/sphinx/jinja2glue.py",
line 174, in 
    self.loaders = [SphinxFileSystemLoader(x) for x in loaderchain]
  File
"/home/luc/virtualenvs/py3/lib/python3.6/site-packages/jinja2/loaders.py",
line 163, in __init__
    self.searchpath = list(searchpath)
TypeError: 'PosixPath' object is not iterable


On 21.08.20 10:10, Matthias Geier wrote:
> Dear list.
>
> I've recently created a new Sphinx HTML theme named "insipid". Its
> documentation (and at the same time a usage example) can be found at:
>
> https://insipid-sphinx-theme.readthedocs.io/
>
> The usage should be really simple:
>
> 1. Install the Python package insipid-sphinx-theme
> 2. Add html_theme = 'insipid' to your conf.py
> 3. Run Sphinx!
>
> It would be great if you could try it out and give feedback (either
> here on the list or at
> https://github.com/mgeier/insipid-sphinx-theme/issues)!
>
> There are certainly many things that can (and should) be improved, I'd
> love to hear your suggestions. Since the theme is very new, I think
> I'm willing to accept quite drastic changes if necessary. Nothing is
> set in stone, so please don't be shy with your suggestions!
>
> There aren't a lot of example projects yet, I've just tried it out on
> a few projects I'm currently working on:
>
> https://nbsphinx.readthedocs.io/en/insipid-theme/
> https://python-rtmixer.readthedocs.io/
> https://mg.readthedocs.io/
> https://jupyter-format.readthedocs.io/
> https://audioscenedescriptionformat.readthedocs.io/
>
> I've mostly tested the theme on multiple browsers on Linux and
> Android, it would be great to get some coverage on Windows, macOS, iOS
> and whatever other OS you are using!
>
> cheers,
> Matthias
>

-- 
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/081af09c-c177-5c6f-3839-0836a9ada581%40gmail.com.

Re: [sphinx-users] Providing an "online link" in the page footer

[Luc Saffre]

Thanks, Matt.  I got inspired by your idea and now use this::

  {%- set url = "https://www.example.com/; + (pagename[:-5] if
pagename.endswith('index') else pagename +"/") -%}
  Online link: {{url}}.

Your example worked on the master page but not on the lower level
directories.

Luc


On 21.08.20 14:57, Matt from Documatt wrote:
> Hello Luc,
> I use the following to "am I on the master page?" (usually file
> index.rst).
>
> Somewhere near to the top of template I define (in action
> <(https://gitlab.com/documatt/sphinx-themes/-/blob/master/sphinx_documatt_theme/sphinx_documatt_theme/layout.html#L8)>):
>
> {%- set ismasterdoc = pagename == master_doc -%}
>
> Later:
>
> {% if ismasterdoc %}
>   https://www.lino-framework.org/;>Online link
> {% else %}
>   https://www.lino-framework.org/{{ pagename|e }}/">Online
> link
> {% endif %}
>
> Matt
> https://blog.documatt.com/sphinx-theming/index.html
>
> On Tue, Aug 18, 2020 at 5:01 PM Luc Saffre  <mailto:luc.saf...@gmail.com>> wrote:
>
> Hello,
>
> in my footer template I usually have something like this::
>
>   https://www.lino-framework.org/{{ pagename|e }}.html"
> <https://www.lino-framework.org/%7B%7Bpagename%7Ce%7D%7D.html>>Online
> link
>
> It's practical for me because usually I watch the generated output
> in my local build, but sometimes I want to see the published
> version of it.
>
> The trick works perfectly for me, except on sites where I use the
> dirhtml builder
> 
> <https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.dirhtml.DirectoryHTMLBuilder>.
> On such a site a can remove the ".html" in the href::
>
>   https://www.lino-framework.org/{{ pagename|e }}"
> <https://www.lino-framework.org/%7B%7Bpagename%7Ce%7D%7D>>Online
> link
>
> which works for most pages, but *not* for the index.rst page of a
> directory. Any thoughts on this?
>
> Luc
> -- 
> 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
> <mailto:sphinx-users+unsubscr...@googlegroups.com>.
> To view this discussion on the web visit
> 
> https://groups.google.com/d/msgid/sphinx-users/85e0e0a5-5334-fae1-db3c-c9ad2046fc70%40gmail.com
> 
> <https://groups.google.com/d/msgid/sphinx-users/85e0e0a5-5334-fae1-db3c-c9ad2046fc70%40gmail.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
> <mailto:sphinx-users+unsubscr...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/sphinx-users/CAOGNDW8HYoQUc4LkMgnJxoUBn7AsRHHxh4HnRDvBR0ex3c80Xg%40mail.gmail.com
> <https://groups.google.com/d/msgid/sphinx-users/CAOGNDW8HYoQUc4LkMgnJxoUBn7AsRHHxh4HnRDvBR0ex3c80Xg%40mail.gmail.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/211e661a-e6bc-3565-76be-f601e3bf1480%40gmail.com.

[sphinx-users] Providing an "online link" in the page footer

[Luc Saffre]

Hello,

in my footer template I usually have something like this::

  https://www.lino-framework.org/{{ pagename|e }}.html">Online
link

It's practical for me because usually I watch the generated output in my
local build, but sometimes I want to see the published version of it.

The trick works perfectly for me, except on sites where I use the
dirhtml builder
.
On such a site a can remove the ".html" in the href::

  https://www.lino-framework.org/{{ pagename|e }}">Online link

which works for most pages, but *not* for the index.rst page of a
directory. Any thoughts on this?

Luc

-- 
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/85e0e0a5-5334-fae1-db3c-c9ad2046fc70%40gmail.com.

Re: [sphinx-users] ANN: Sphinx-3.1.2 is out

[Luc Saffre]

I did "pip install -U sphinx" and then rebuilt all my projects without
problem.
Thanks for your work, Takeshi.

Luc

On 05.07.20 13:50, Komiya Takeshi wrote:
> Hi all,
>
> Today, I released Sphinx-3.1.2. It contains some bug fixes (mainly
> autodoc and CSS troubles).
>
> For more detail, please check the CHANGES file:
> https://github.com/sphinx-doc/sphinx/blob/3.1.x/CHANGES
>
> Enjoy documentation!
>
> Thanks,
> Takeshi KOMIYA
>

-- 
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/b69f5ae2-4b82-6028-2509-ebd4edad15bc%40gmail.com.

Re: [sphinx-users] ANN: Sphinx-3.1.1 is out

[Luc Saffre]

Successfully built all my projects with the new version.  Thanks for
your ongoing work on this project!

Luc

On 14.06.20 07:13, Komiya Takeshi wrote:
> Hi all,
>
> Today, I released Sphinx-3.1.1. It contains some bug fixes.
>
> For more detail, please check the CHANGES file:
> https://github.com/sphinx-doc/sphinx/blob/3.1.x/CHANGES
>
> Enjoy documentation!
>
> Thanks,
> Takeshi KOMIYA
>

-- 
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/5b5fb659-6b65-cd51-3fdf-77394ec98529%40gmail.com.

Re: [sphinx-users] Sphinx-3.0.0b1 released.

[Luc Saffre]

I ran it on all my doctrees (more than 20), and the only "problems" were
duplicate glossary entries or object definitions, IOW the new version
works perfect for me, and better than 2.4-

Thanks for your work!

Luc

On 22.03.20 17:26, Komiya Takeshi wrote:
> Hi all,
>
> We just released Sphinx-3.0.0b1.
> It has many changes including incompatible ones.
> Please confirm it working fine on your documents.
>
> In detail, please see CHANGES:
> https://github.com/sphinx-doc/sphinx/blob/3.0.x/CHANGES
>
> You can use it with: pip install --pre Sphinx
>
> Since this is a beta release, we expect that you may encounter bugs.
> If you find a bug, please file an issue on Github issues:
> https://github.com/sphinx-doc/sphinx/issues
>
> Thanks,
> Takeshi KOMIYA
>

-- 
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/b41aa0cf-f9b2-5bc7-40c0-75908d055df6%40gmail.com.

Re: [sphinx-users] Building docs from multiple repos on one site

[Luc Saffre]

Not exactly the same, but maybe inspiring: we have a rather complex
system of interdependent Python packages and Sphinx doctrees, and I try
to document it on the following page:

https://www.lino-framework.org/dev/writedocs.html

Luc

On 06.12.19 02:25, M.B. wrote:
> We have a Sphinx documentation site for our software product, nothing
> fancy. It hosts our general documentation, let's say at *docs.xyz.org*
>
> Our software is made up of many packages across many repositories on
> github, many of which are community contributed (we're open source).
> We're looking for a way to push package documentation from
> disconnected repos (written in rst, kept in a top level */docs*
> directory in the repo) to our main sphinx site.
>
> The naming structure could be something like
> *docs.xyz.org/version/package_name* for the package ReadMe and
> *docs.xyz.org/version/package_name/tutorials* for any tutorials, but
> it could also be something like
> *tutorials.xyz.org/version/package_name*, or anything similar.
>
> Is anything like this possible? I can't find any information on
> accumulating and rendering pages from across multiple repos.
>
> Any info or direction is greatly appreciated!
> -- 
> 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/6e3a761f-fae8-433b-b3ff-0be2e30cc11c%40googlegroups.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/d3592508-fc04-cd99-a390-50f7c5838842%40gmail.com.

Re: [sphinx-users] I've started GitHub sponsors

[Luc Saffre]

How will you receive that money? How much does GitHub get for their
service? I searched their docs

but did not get any answer.

Luc

On 01.12.19 10:36, Komiya Takeshi wrote:
> Hi all,
>
> I'm tk0miya, one of maintainers of Sphinx. Recently, I've started
> GitHub sponsors program at https://github.com/sponsors/tk0miya .
> It will help my development.
>
> If you have a fun for Sphinx, please consider to become my sponsor :-)
>
> Thanks,
> Takeshi KOMIYA
>

-- 
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/a8ad3243-9023-e506-5b96-32e785e5ee69%40gmail.com.

Re: [sphinx-users] list of intersphinx mapping resources

[Luc Saffre]

Andy, I have no suggestion. I don't see how a global list could be
useful. Why do you want such a collection? What would be the purpose?

Maybe off topic but I maintain a few dozens Sphinx doctrees that partly
depend on each other, and for managing their intersphinx mappings I use
my self-written package atelier
<https://atelier.lino-framework.org/usage.html> which has a function
atelier.sphinxconf.interproject()
<https://atelier.lino-framework.org/api/atelier.sphinxconf.interproject.html>

Luc


On 17.11.19 08:10, Andy wrote:
> ok,
> Can people post some here and I'll start collecting 
>
> Andy
>
> On Sun, 17 Nov 2019 at 07:04, Luc Saffre  <mailto:luc.saf...@gmail.com>> wrote:
>
> With *all* available intersphinx mappings? Definitively not. You'd
> better maintain your own list of those you want. And if your list
> is potentially useful to others, you should publish it as a python
> package so that everybody can use it by doing "pip install
> andys_mappings" and add "from andys_mappings import
> intersphinx_mapping". to their conf.py
>
> hth,
> Luc
>
> On 15.11.19 13:06, Andy Cheesman wrote:
>> Hi people
>>
>> Is there a list somewhere on the internet with all avaialble
>> intersphinx mappings, including non python languages?
>> I've had a good search to no avail
>>
>> Thanks
>>
>> Andy 
>> -- 
>> 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
>> <mailto:sphinx-users+unsubscr...@googlegroups.com>.
>> To view this discussion on the web visit
>> 
>> https://groups.google.com/d/msgid/sphinx-users/9b07d37d-1e34-47e2-973d-ab1089a0449a%40googlegroups.com
>> 
>> <https://groups.google.com/d/msgid/sphinx-users/9b07d37d-1e34-47e2-973d-ab1089a0449a%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
> <mailto:sphinx-users+unsubscr...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/sphinx-users/CADBoBxB96PG1xfpGwzVJMuSO5WtxVfDZfiyKQVGqZvz%3DkrhaTw%40mail.gmail.com
> <https://groups.google.com/d/msgid/sphinx-users/CADBoBxB96PG1xfpGwzVJMuSO5WtxVfDZfiyKQVGqZvz%3DkrhaTw%40mail.gmail.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/21f86a09-3d34-e480-ffb7-74a645557f5d%40gmail.com.

Re: [sphinx-users] Translation - How to get one pot files instead of many

[Luc Saffre]

Hi Takeshi,

aha, thanks, that was new for me. I now read about translation memory
<https://en.wikipedia.org/wiki/Translation_memory>.
Do you know whether https://translatewiki.net also has this feature? I
would prefer translatewiki over transifex because transifex uses
proprietary software.

Luc

On 26.10.19 12:28, Komiya Takeshi wrote:
> Hi Luc,
>
> I think translation memory feature will help your case. For example,
> transifex supports it. So it can refill translation easily if contents
> are moved to other file.
>
> Thanks,
> Takeshi KOMIYA
>
> 2019年10月26日(土) 16:29 Luc Saffre :
>> I confirm that question. I didn't yet start translating one of my projects 
>> because I felt this issue as well. I thought what will happen if I move 
>> content from one page to another page, or when I change the page name? What 
>> must I know to avoid losing my translation work?
>> Seems that this needs more documentation.
>> Luc
>>
>> On 24.10.19 11:32, Arthur wrote:
>>
>> Hello,
>>
>> I see on the sphinx-doc repo that there is only one pot file for the english 
>> version, instead of many. See 
>> https://github.com/sphinx-doc/sphinx/tree/master/sphinx/locale.
>>
>> When I use gettext, I get one pot file per RST file. How can I just get one 
>> document? Would it make Transifex integration easier to have one pot file? 
>> Or do I need to declare a bulk mapping?
>>
>> 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/ccd79615-9668-4d68-b4c0-b4857e027c30%40googlegroups.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 view this discussion on the web visit 
>> https://groups.google.com/d/msgid/sphinx-users/ca8f0ccc-93b1-23a2-de65-80fd5e4dd017%40gmail.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/aee011e2-5219-ba6b-e2a5-3906c245ef7f%40gmail.com.

Re: [sphinx-users] Translation - How to get one pot files instead of many

[Luc Saffre]

I confirm that question. I didn't yet start translating one of my
projects because I felt this issue as well. I thought what will happen
if I move content from one page to another page, or when I change the
page name? What must I know to avoid losing my translation work?
Seems that this needs more documentation.
Luc

On 24.10.19 11:32, Arthur wrote:
> Hello,
>
> I see on the sphinx-doc repo that there is only one pot file for the
> english version, instead of many. See
> https://github.com/sphinx-doc/sphinx/tree/master/sphinx/locale.
>
> When I use gettext, I get one pot file per RST file. How can I just
> get one document? Would it make Transifex integration easier to have
> one pot file? Or do I need to declare a bulk mapping?
>
> 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/ccd79615-9668-4d68-b4c0-b4857e027c30%40googlegroups.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 view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/ca8f0ccc-93b1-23a2-de65-80fd5e4dd017%40gmail.com.

Re: [sphinx-users] First steps with Pyhton and Sphinx

[Luc Saffre]

Your project was almost perfect, there was only one detail missing: in
every `__init___.py` you must explicitly tell autosummary which
subpackages you want to include. See my diff below.

HTH
Luc

$ git diff
diff --git a/buhtzsphinx/__init__.py b/buhtzsphinx/__init__.py
index 76a9a4a..77157f5 100644
--- a/buhtzsphinx/__init__.py
+++ b/buhtzsphinx/__init__.py
@@ -2,6 +2,12 @@
 This is buhtzsphinx brief line.
 
 More complex.
+
+.. autosummary::
+   :toctree:
+
+   mycode
+
 """
 
 from .mycode import *


On 04.10.2018 23:59, c.bu...@posteo.jp wrote:
> Dear Luc,
>
> thanks for your explanations.
>
> I updated my code and pushed it to upstream.
>
> But it still not working here. Can you give it a try with my code?
> .
>

-- 
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] First steps with Pyhton and Sphinx

[Luc Saffre]

Yes, atelier simplifies my life but for you it makes things more
difficult to understand...

I guess that you should have a look at the
atelier.sphinxconf.configure() function:
https://github.com/lino-framework/atelier/blob/master/atelier/sphinxconf/__init__.py#L64

configure() updates the globals() namespace of the conf.py file, so when
it does
*globals_dict.update(foo='bar')* then that's as if you would type
*foo='bar'* in your conf.py file.

Quick translated excerpt of autosummary options that might be relevant
for you:

autodoc_default_options={ 'members': None, 'show-inheritance': None}
autodoc_member_order='bysource'
autodoc_inherit_docstrings=False

HTH
Luc

On 03.10.2018 14:44, c.bu...@posteo.jp wrote:
> Dear Luc,
>
> thank you for this valuable hint. Your example doc looks awesome and
> exactly as this what was in my mind.
>
> The test with my own code did not work.
> https://gitlab.com/buhtz/buhtz-sphinx
> I always do a "make html" in the doc-directory to generate the doc.
>
> But I have not copied your conf.py exactly.
> https://gitlab.com/buhtz/buhtz-sphinx/blob/master/doc/source/conf.py
> Because I didn't understand all details of your conf.py. What is this
> with the "import atelier" in it? Why do you use the package that should
> be documented in your conf.py file?
> You also use a lot more atelier calls in the conf.py file.
>
> It would help my understanding to see a minimal example.
>
> The sphinx-doc website about autosummary doesn't explain how to
> configure a complete project environment to run.
> .
>

-- 
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] First steps with Pyhton and Sphinx

[Luc Saffre]

Did you see autosummary

then?

Result example: http://atelier.lino-framework.org/api/index.html
Source code:
https://raw.githubusercontent.com/lino-framework/atelier/master/docs/api/index.rst
conf.py : https://github.com/lino-framework/atelier/blob/master/docs/conf.py

Luc

On 02.10.2018 00:30, c.bu...@posteo.jp wrote:
> I also found the autoapi extension.
> But even this is far away from being "auto" because I have to write all
> members into the __all__ variable in each module.
>
> The point for me in "auto" is I don'T want to think about if I have to
> add a new created member to an __all__ variable or write it into an
> rst-file or whatever.
>
> Isn't there nothing out there doing this automatic?
> It is just py-file parsing and then rearrange the data to a html (or
> whatever) file.
>
> I don't see how sphinx and Co can improve my workflow and save my time
> resources.
>
> I am sure there is an advantage of Sphinx because the whole world is
> using it. But I am not seeing it. So please help the blind. ;)
>
> On 2018-09-28 21:40 Matthias Geier  wrote:
>> On Thu, Sep 27, 2018 at 4:09 PM c.buhtz wrote:
>>> Dear Matthias,
>>>
>>> I fixed the module name and added a autodoc command to the rst file
>>> - see in upstream.
>>>
>>> The result is the same. The "module index" in the docs is empty.  
>> OK, we are getting closer.
>>
>> The first little thing is a missing space. You wrote:
>>
>> .. automodule::buhtzsphinx
>>
>> but it should be:
>>
>> .. automodule:: buhtzsphinx
>>
>> But it still doesn't work ...
>>
>> The next problem is that what you wrote into __main__.py should
>> actually go into __init__.py.
>>
>> If you do that, you'll get something! Congratulations!
>>
>> But the docs for myclass.MyClass are still missing ...
>>
>> It turns out that I was wrong in thinking that "automodule" would
>> automatically include submodules. It looks like it doesn't. You'll
>> have to specify each module separately, e.g.:
>>
>> .. automodule:: buhtzsphinx.myclass
>> :members:
>>
>> This should finally show the docs of MyClass!
>>
>> cheers,
>> Matthias
>>

-- 
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] Sphinx-1.8.0 released

[Luc Saffre]

Oops, that workaround doesn't work. ATM I can avoid it only by saying
"export LC_TIME=en_GB.UTF-8" before running sphinx-build.

Luc


On 18.09.2018 09:40, Luc Saffre wrote:
> PS : more concretely as a workaround, I added the following lines to my
> conf.py file:
>
> import os
> os.environ['LC_TIME'] = 'en_UK.UTF-8'
>
> Works for me.
> Luc
>
> On 13.09.2018 13:55, Luc Saffre wrote:
>> Thanks again!
>>
>> This time I have a nice problem which caused me a few hours of fun:
>> http://luc.lino-framework.org/blog/2018/0913.html
>>
>> Summary: Sphinx version 1.8 sets the locale to the one defined by the
>> LC_TIME environment variable on my machine, despite the fact that in my
>> conf.py I have language = 'en'. Yes, feedformatter fails when the locale
>> is not English, they should fix this, but I don't see why Sphinx
>> behaviour changes with the value of LC_TIME environment variable on my
>> machine.  Yes, I live in Estonia, but that site with language = "en"
>> should have nothing Estonian.
>>
>> Luc
>>
>>
>> On 12.09.2018 19:22, Komiya Takeshi wrote:
>>> Hi all,
>>>
>>> I'm delighted to announce the release of Sphinx 1.8.0 final, now available 
>>> on
>>> the Python package index at <https://pypi.org/project/Sphinx/>.
>>>
>>> It includes about 45 new features, 26 bug fixes and 25 incompatible
>>> changes.
>>>
>>> For the full changelog, go to
>>> <http://www.sphinx-doc.org/en/master/changes.html>.
>>> Thanks to all collaborators and contributers!
>>>
>>> What is it?
>>> ===
>>>
>>> Sphinx is a tool that makes it easy to create intelligent and beautiful
>>> documentation for Python projects (or other documents consisting of
>>> multiple reStructuredText source files).
>>>
>>> Website: http://sphinx-doc.org/
>>> IRC: #sphinx-doc on irc.freenode.net
>>>
>>> Enjoy!
>>>

-- 
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] Sphinx-1.8.0 released

[Luc Saffre]

PS : more concretely as a workaround, I added the following lines to my
conf.py file:

import os
os.environ['LC_TIME'] = 'en_UK.UTF-8'

Works for me.
Luc

On 13.09.2018 13:55, Luc Saffre wrote:
> Thanks again!
>
> This time I have a nice problem which caused me a few hours of fun:
> http://luc.lino-framework.org/blog/2018/0913.html
>
> Summary: Sphinx version 1.8 sets the locale to the one defined by the
> LC_TIME environment variable on my machine, despite the fact that in my
> conf.py I have language = 'en'. Yes, feedformatter fails when the locale
> is not English, they should fix this, but I don't see why Sphinx
> behaviour changes with the value of LC_TIME environment variable on my
> machine.  Yes, I live in Estonia, but that site with language = "en"
> should have nothing Estonian.
>
> Luc
>
>
> On 12.09.2018 19:22, Komiya Takeshi wrote:
>> Hi all,
>>
>> I'm delighted to announce the release of Sphinx 1.8.0 final, now available on
>> the Python package index at <https://pypi.org/project/Sphinx/>.
>>
>> It includes about 45 new features, 26 bug fixes and 25 incompatible
>> changes.
>>
>> For the full changelog, go to
>> <http://www.sphinx-doc.org/en/master/changes.html>.
>> Thanks to all collaborators and contributers!
>>
>> What is it?
>> ===
>>
>> Sphinx is a tool that makes it easy to create intelligent and beautiful
>> documentation for Python projects (or other documents consisting of
>> multiple reStructuredText source files).
>>
>> Website: http://sphinx-doc.org/
>> IRC: #sphinx-doc on irc.freenode.net
>>
>> Enjoy!
>>

-- 
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] Sphinx-1.8.0 released

[Luc Saffre]

PS : more concretely as a workaround, I added the following lines to my
conf.py file:

import os
os.environ['LC_TIME'] = 'en_UK.UTF-8'

Works for me.
Luc

On 13.09.2018 13:55, Luc Saffre wrote:
> Thanks again!
>
> This time I have a nice problem which caused me a few hours of fun:
> http://luc.lino-framework.org/blog/2018/0913.html
>
> Summary: Sphinx version 1.8 sets the locale to the one defined by the
> LC_TIME environment variable on my machine, despite the fact that in my
> conf.py I have language = 'en'. Yes, feedformatter fails when the locale
> is not English, they should fix this, but I don't see why Sphinx
> behaviour changes with the value of LC_TIME environment variable on my
> machine.  Yes, I live in Estonia, but that site with language = "en"
> should have nothing Estonian.
>
> Luc
>
>
> On 12.09.2018 19:22, Komiya Takeshi wrote:
>> Hi all,
>>
>> I'm delighted to announce the release of Sphinx 1.8.0 final, now available on
>> the Python package index at <https://pypi.org/project/Sphinx/>.
>>
>> It includes about 45 new features, 26 bug fixes and 25 incompatible
>> changes.
>>
>> For the full changelog, go to
>> <http://www.sphinx-doc.org/en/master/changes.html>.
>> Thanks to all collaborators and contributers!
>>
>> What is it?
>> ===
>>
>> Sphinx is a tool that makes it easy to create intelligent and beautiful
>> documentation for Python projects (or other documents consisting of
>> multiple reStructuredText source files).
>>
>> Website: http://sphinx-doc.org/
>> IRC: #sphinx-doc on irc.freenode.net
>>
>> Enjoy!
>>

-- 
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] Sphinx-1.8.0 released

[Luc Saffre]

Thanks again!

This time I have a nice problem which caused me a few hours of fun:
http://luc.lino-framework.org/blog/2018/0913.html

Summary: Sphinx version 1.8 sets the locale to the one defined by the
LC_TIME environment variable on my machine, despite the fact that in my
conf.py I have language = 'en'. Yes, feedformatter fails when the locale
is not English, they should fix this, but I don't see why Sphinx
behaviour changes with the value of LC_TIME environment variable on my
machine.  Yes, I live in Estonia, but that site with language = "en"
should have nothing Estonian.

Luc


On 12.09.2018 19:22, Komiya Takeshi wrote:
> Hi all,
>
> I'm delighted to announce the release of Sphinx 1.8.0 final, now available on
> the Python package index at .
>
> It includes about 45 new features, 26 bug fixes and 25 incompatible
> changes.
>
> For the full changelog, go to
> .
> Thanks to all collaborators and contributers!
>
> What is it?
> ===
>
> Sphinx is a tool that makes it easy to create intelligent and beautiful
> documentation for Python projects (or other documents consisting of
> multiple reStructuredText source files).
>
> Website: http://sphinx-doc.org/
> IRC: #sphinx-doc on irc.freenode.net
>
> Enjoy!
>

-- 
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] Sphinx-1.8.0b1 released.

[Luc Saffre]

Maybe not intended, but it is correct behaviour. My code was "wrong"
because it started a parser without giving a source.
Yes, the code of the graphviz extension could check wether
current_source is given before accessing it, that would make it more
fool-proof.
Luc

On 21/08/18 15:57, Komiya Takeshi wrote:
> Hi Luc,
>
> Thank you for very detailed report!
> About state.document.current_source is not intended change. So I'll
> check it later.
>
> Thanks,
> 2018年8月21日(火) 17:23 Luc Saffre :
>> I ran the new version on all my projects without problems (except some 
>> changes in my own code, details in my blog).
>> Thanks for your  work on maintaining Sphinx!
>> Luc
>>
>> On 20/08/18 19:36, Komiya Takeshi wrote:
>>
>> Hi all,
>>
>> We just released 1.8.0b1.
>> It includes much of improvements. And we believe it will help you.
>>
>> In detail, please see CHANGES:
>> https://github.com/sphinx-doc/sphinx/blob/1.8.0b1/CHANGES
>>
>> You can use it with: pip install --pre Sphinx
>>
>> Since this is a beta release, we expect that you may encounter bugs.
>> If you find a bug, please report it on github issues:
>> https://github.com/sphinx-doc/sphinx/issues
>>
>> Thanks,
>> Takeshi KOMIYA
>>
>>

-- 
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] Sphinx-1.8.0b1 released.

[Luc Saffre]

I ran the new version on all my projects without problems (except some
changes in my own code, details in my blog
).
Thanks for your  work on maintaining Sphinx!
Luc

On 20/08/18 19:36, Komiya Takeshi wrote:
> Hi all,
>
> We just released 1.8.0b1.
> It includes much of improvements. And we believe it will help you.
>
> In detail, please see CHANGES:
> https://github.com/sphinx-doc/sphinx/blob/1.8.0b1/CHANGES
>
> You can use it with: pip install --pre Sphinx
>
> Since this is a beta release, we expect that you may encounter bugs.
> If you find a bug, please report it on github issues:
> https://github.com/sphinx-doc/sphinx/issues
>
> Thanks,
> Takeshi KOMIYA
>

-- 
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] Custom toctree generation (not global - not local)

[Luc Saffre]

Hi Brad,

I used individual pages for each subdivision in my Lino Developer's
Guide . Every "section"
(the first section is Getting started
) contains a set of
"chapters" (each chapter being one page).
Look at the "Show source" link at the bottom of each page.

hth,
Luc


On 27/07/18 16:50, Brad Miller wrote:
> Hello all,
>
> I have a bunch of documents that are structured like this:
>
>
> index.rst
>
> Chapter1/toctree.rst
>          section1.rst
>          section2.rst
>
> Chapter2/toctree.rst
>          section1.rst
>          section2.rst
>
> The global index.rst file just includes Chapter1/toctree and
> Chapter2/toctree  etc, and the toctrees for each chapter include all
> of the sections for that chapter.
>
> What I would like to do is have a table of contents for each chapter
> that includes all of the sections contained, I would display this toc
> in a sidebar or as a dropdown from the navbar.    Any ideas or hints
> on how I might make that happen?
>
> Thanks,
>
> Brad
>
> -- 
> 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.


-- 
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] Sphinx-1.7.0 has been released

[Luc Saffre]

Thanks, Komiya, for your ongoing work. I rebuilt all my doctrees without
problem. (I also wrote about it in my blog
)
Luc

On 12/02/18 10:01, Komiya Takeshi wrote:
> Hi all,
>
> I'm delighted to announce the release of Sphinx 1.7.0, now available on
> the Python package index at .
>
> It includes about 34 new features and 31 bug fixes for the 1.6 release series.
>
> For the full changelog, go to
> .
> Thanks to all collaborators and contributers!
>
> What is it?
> ===
>
> Sphinx is a tool that makes it easy to create intelligent and beautiful
> documentation for Python projects (or other documents consisting of
> multiple reStructuredText source files).
>
> Website: http://sphinx-doc.org/
> IRC: #sphinx-doc on irc.freenode.net
>
> Enjoy!
> --
> Takeshi KOMIYA
>

-- 
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] Sphinx-1.7.0b1 has been released

[Luc Saffre]

Yes, that's what I missed! Thanks Shirou for the pointer.
I verified that indeed it works, and I also updated my blog entry.

Luc

On 17/01/18 04:34, shirou wrote:
> Hi,
>
> Since sphinx 1.7.0b1 is pre-release, could you try to install again
> with --pre option ?
>
> Since pip 1.4, pip does not search or install pre-release in default.
> https://pip.pypa.io/en/stable/reference/pip_install/?highlight=pre#pre-release-versions
>
>
> Thanks,
> WAKAYAMA Shirou
>
>
> 2018-01-17 3:15 GMT+09:00 Luc Saffre <luc.saf...@gmail.com>:
>> Thanks for your continued work, Takeshi!
>>
>> Here is my feedback copied from my blog:
>>
>> I tested it on my projects. Note that pip install -U sphinx doesn’t install
>> it, I had to pull the github repo and use pip install -e. Or did I miss
>> something?
>>
>> It worked flawlessly, except for a problem when building The Lino Book:
>>
>> SphinxWarning: /book/docs/specs/cal.rst:1010:duplicate object description of
>> lino_xl.lib.cal.Plugin, other instance in
>> /book/docs/api/lino_xl.lib.cal.rst, use :noindex: for one of them
>>
>> No, I cannot use :noindex: for one of them because my document structure is
>> based on the asumption that autodoc ignores members that have no docstring.
>> For example the page which documents the lino_xl.lib.cal module is
>> automatically generated, but it must not contain a definition for
>> lino_xl.lib.cal.Plugin which has a prosa description in The calendar plugin.
>>
>> It took me some time to find the reason. I first searched for
>> autodoc-process-docstringand autodoc_default_flags but could not find any
>> explanation. I added 'no-undoc-members', no change.
>>
>> The explanation was that Sphinx didn’t consider the docstring as empty
>> because it took the docstring of the parent class.
>>
>> The “guilty” is therefore a new configuration setting
>> autodoc_inherit_docstrings which default value is True. I fixed my problem
>> by setting it to False.
>>
>> Luc
>>
>>
>> On 15/01/18 16:42, Komiya Takeshi wrote:
>>
>> Hi all,
>>
>> We just released 1.7.0b1.
>> It includes much of improvements. And we believe it will help you.
>>
>> In detail, please see CHANGES:
>> https://github.com/sphinx-doc/sphinx/blob/1.7.0b1/CHANGES
>>
>> Since this is a beta release, we expect that you may encounter bugs.
>> If you find a bug, please report it on github issues:
>> https://github.com/sphinx-doc/sphinx/issues
>>
>> Thanks,
>> Takeshi KOMIYA
>>
>>
>> --
>> 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.


-- 
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] Sphinx-1.7.0b1 has been released

[Luc Saffre]

Thanks for your continued work, Takeshi!

Here is my feedback copied from my blog
:

I tested it on my projects. Note that |pip install -U sphinx| doesn’t
install it, I had to pull the github repo and use |pip install -e|. Or
did I miss something?

It worked flawlessly, except for a problem when building The Lino Book
:

  * SphinxWarning: /book/docs/specs/cal.rst:1010:duplicate object
description of lino_xl.lib.cal.Plugin, other instance in
/book/docs/api/lino_xl.lib.cal.rst, use :noindex: for one of them

No, I cannot |use :noindex: for one of them| because my document
structure is based on the asumption that autodoc ignores members that
have no docstring. For example the page which documents
the|lino_xl.lib.cal|
 
module
is automatically generated, but it must not contain a definition
for |lino_xl.lib.cal.Plugin|
 which
has a prosa description in The calendar plugin
.

It took me some time to find the reason. I first searched
for autodoc-process-docstringand autodoc_default_flags but could not
find any explanation. I added |'no-undoc-members'|, no change.

The explanation was that Sphinx didn’t consider the docstring as empty
because it took the docstring of the parent class.

The “guilty” is therefore a new configuration
setting autodoc_inherit_docstrings which default value is True. I fixed
my problem by setting it to False.

Luc


On 15/01/18 16:42, Komiya Takeshi wrote:
> Hi all,
>
> We just released 1.7.0b1.
> It includes much of improvements. And we believe it will help you.
>
> In detail, please see CHANGES:
> https://github.com/sphinx-doc/sphinx/blob/1.7.0b1/CHANGES
>
> Since this is a beta release, we expect that you may encounter bugs.
> If you find a bug, please report it on github issues:
> https://github.com/sphinx-doc/sphinx/issues
>
> Thanks,
> Takeshi KOMIYA
>

-- 
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] How to make a link for absolute import in python?

[Luc Saffre]

Does your second example import at all? Because AFAICS it should be::

  import project.bar

  class foo(project.bar)
  ...

Luc

On 12/12/17 09:32, wenhao...@leapmind.io wrote:
> As title, if I use relative import, `make html` will create a html that
> contains such code to link the reference. 
> 
> 
> import .bar
> 
> class foo(bar)
>     ...
> 
> 
> But if I use absolute import, it does not.
> 
> import project.bar
> 
> class foo(bar)
>     ...
> 
> 
> Any ideas?
> 
> -- 
> 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.

-- 
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] How a JavaScript RST parser could benefit Sphinx

[Luc Saffre]

Seikichi looks promizing. I would first try to join it. Yes, there is
some work to do, but you won't have less work if you start from scratch.

Luc

On 13/12/16 04:54, Michael Gielda wrote:
> Hi everyone,
> 
> I wanted to spark up a discussion about reaching out further with Sphinx
> by an activity not strictly related to Sphinx development per se, but in
> my opinion in reality very much interdependent with the framework.
> 
> Over the years using Sphinx I have found its use of reStructuredText
> mostly a blessing but also a little bit of a curse. It's a very powerful
> and extensible format, and as such very well suited to complex,
> technical documents. But some of its aspects are quite quirky (smaller
> problem), and most project/code management frameworks (GitLab, Redmine,
> GitHub, Bitbucket) that I use which for me double as 'online review
> frameworks' have limited support of it (bigger problem). That is, thanks
> to the availability of some ruby parsers, the support is there in
> general, but it's limited as opposed to Markdown, which is a first-class
> citizen on the Web. Notably, Sphinx roles are not supported anywhere, so
> any less "rSTy" and more "Sphinxy" type of documentation will render
> very badly anyway (or throw 'role not found' errors), reducing the
> usability of the parser in the first place.
> 
> This is of course arguable, but I think that the reason for Markdown's
> popularity at least partly has been the plethora of JavaScript
> implementations which just made it spread over the web like a virus. Of
> course, it's great for short documents, but as soon as you add
> complexity, it just collapses (which is a shame but I've never been able
> to build anything bigger with Markdown). MkDocs is OK but I find Sphinx
> better feature- and stability-wise.
> 
> It would be awesome to have some more Web support for Sphinx, and I
> believe this would happen if we had a simple yet extendible javascript
> parser where e.g. custom roles could be implemented. This would in turn
> spawn editors, IDEs, online tooling etc, which would popularise Sphinx
> itself.
> 
> The online editor at http://rst.ninjs.org/ is nice as a demo but not
> really practical as it is not a client-side solution.
> AsciiDoctor has https://github.com/asciidoctor/asciidoctor.js which -
> even if a bit hacky (in the sense of being a conversion of the original
> code to JavaScript, not a reimplementation) - works quite well (see
> https://asciidoclive.com/edit/scratch/1). No server side code there as
> far as I can see.
> 
> I haven't seen any advanced effort in that direction - the only project
> that addresses the problem (but does not solve it yet) is
> https://github.com/seikichi/restructured - it does offer basic support
> but the sheer number of empty tickboxes shows that there is still a
> long, long way to go.
> 
> Of course, question is, why don't I write it myself. Answer: I'm no
> JavaScript guru, neither am I a seasoned parser writer - but I can
> assist in all sort of documentation, debug and testing activity, as
> probably can my team (we have tons of RST writeup we work with on a
> daily basis). [by the way - I had once tried converting the docutils
> code to js with a converter, but it's just huge... gave up quite quick]
> 
> My question is, whether there are more like-minded people out there who
> too think this would be beneficial. Or perhaps I am omitting something
> important, or not understanding things well enough?
> Perhaps we could support seikichi, or spawn another, joint effort, at
> least loosely endorsed by the Sphinx community?
> 
> 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.

-- 
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] Sphinx 1.5 released

[Luc Saffre]

#2336 is unfortunately still open, but I adapted my patch (once more):

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

Takayuki, is there a problem with above patch? I am surprised to get no
feedback.

Luc

On 10/12/16 07:23, Takayuki Shimizukawa wrote:
> Hi all,
> 
> I'm very happy to announce the release of Sphinx 1.5-final available on
> the Python package index at .
> 
> Sphinx-1.5 includes many updates from 1.4.9 version:
> 
> * 67 features
> * 38 incompatible changes
> * 3 deprecations
> * 52 fixes of bugs/buglets
> 
> For the full changelog, go to
> .
> Thanks to all collaborators and contributers!
> I especially appreciate tk0miya who made a great contribution over the
> past year.
> 
> 
> What is it?
> ===
> 
> Sphinx is a tool that makes it easy to create intelligent and beautiful
> documentation for Python projects (or other documents consisting of
> multiple reStructuredText source files).
> 
> Website: http://sphinx-doc.org/
> IRC: #sphinx-doc on irc.freenode.net 
> 
> Enjoy!
> --
> Takayuki SHIMIZUKAWA
> http://about.me/shimizukawa
> 
> -- 
> 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.

-- 
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: Advice needed on automatically generated documentation

[Luc Saffre]

If you do "from atelier.rstgen import table" and then add 'table' to
your jinja context, then you should be able to do it as follows::

  .. jinja:: messages

  {% table(['Message Code', 'Message name'], stc.items()) %}

http://atelier.lino-framework.org/api/atelier.rstgen.html
(I am the author)

Luc



On 11/08/16 09:54, Markus wrote:
> Thanks to all who replied. I'm now using the sphinx-jinja extension
> and it works pretty well. I have no trouble using JSON files as input.
>
> At first I had a little trouble getting the whitespace generated
> correctly, but this was fixed by correctly using -%} and {%- when
> generating tables, and manually inserting whitespace like so:
>
> .. jinja:: messages
>
>  
>Message Code  Message Name
>  
>{% for k, v in stc -%}
>{{"%-13s  %s\n" % (k, v)}}
>{%- endfor %}
>  
>
> Markus
> -- 
> 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.


-- 
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] mailto

[Luc Saffre]

I'd guess that you need the `raw` directive:

http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw-data-pass-through

Luc


On 01/04/16 20:48, Paolo Cavallini wrote:
> Hi all,
> I do not find a way to add a mailto like this?
> mailto:i...@faunalia.it?subject=QGIS courses">write us for info
> I searched the documentation, and could not find it.
> Thanks a lot.
> 

-- 
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] Intersphinx for links among our own projects?

[Luc Saffre]

I solved this for me by organizing my projects so that their docs don't
refer to each other in a circular way, and by organizing my builds so
that the order of dependency is respected:

a (top-level, no intersphinx refs)
b can refer to a
c can refer to b and a

Luc

On 22/01/16 19:30, Ned Batchelder wrote:
> At edX, we're using intersphinx to link among our own projects.  But
> it's designed to pull .inv files from readthedocs.  This means if we add
> a new reference between projects, the build will fail until the target
> has been published.  I tried using the second value in the mapping tuple
> to point to a local file, but the file hadn't been created yet.
> 
> Is there a way to generate all the .inv files in a first pass, and then
> do the full build of the doc?
> 
> --Ned.
> 
> -- 
> 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.

-- 
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] embed google groups forum to sphinx doc

[Luc Saffre]

Your code works perfectly when I try it. See yourself:

  http://luc.lino-framework.org/blog/2016/0107a.html

One observation: it does *not* work when I open the generated file from
my machine, I had to publish it to my website.

Luc

On 07/01/16 07:32, Bachir Aoun wrote:
> I am trying to embed my google-groups forum into the docstring of my
> python code so Sphinx generated html will embed it into the web page's.
> my code as as the following:
> 
> |
> """
> Questions and Answers forum
> ===
> .. raw:: html
> 
> 
>  src="javascript:void(0)"
>  scrolling="no"
>  frameborder="0"
>  width="900"
>  height="700">
>
> 
>
>  document.getElementById('forum_embed').src =
> 'https://groups.google.com/forum/embed/?place=forum/MYPACKAGE'
> + '&showsearch=true&showpopout=true&showtabs=false'
> + '&parenturl=' + encodeURIComponent(window.location.href);
>
> 
> 
> """
> |
> 
> 
> but the output is an empty space after the title *Questions and Answers
> forum*
> I am not very experimented with html neither javascripts nor templating
> so excuse my ignorance if my question is not complete. But I would like
> to know how to make this works :)
> 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.

-- 
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] How can I delete the word "DOcumentation!" in the header?

[Luc Saffre]

Have a look at the configuration option html_title in your conf.py file.

http://sphinx-doc.org/config.html#confval-html_title

There is also html_short_title

Luc

On 30/12/15 00:04, Alexandre Almeida wrote:
> Hi!
> 
> I am a new member.
> I've installed Sphinx and am trying to make some some changes in the
> layout (I use the Alabaster theme).
> Does anybody know about how to delete the word "Documentation" after the
> name of the project?
> 
> Alexandre.
> 
> -- 
> 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.

-- 
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] navigation bar has disappeared

[Luc Saffre]

Hey cool! Thanks for sharing this! I can confirm this behaviour. I added
these lines to my layout.html templates:

{% block relbar1 %}
{{relbar() }}
{{ super() }}
{% endblock %}

{% block relbar2 %}
{{relbar() }}
{{ super() }}
{% endblock %}

Looks indeed as if the relbar() macro no longer gets called by the
default relbarN blocks.
I don't see that duplicate navigation bar (probably because before I had
no bar at all on all my doctrees).

I am using Sphinx 1.3.1 and Jinja2 version 2.8. Please verify your Jinja
versions (the problem might be there).

My problem is fixed (though not in an elegant way).

Luc


On 20/10/15 20:26, Jeff McKenna wrote:
> I just discovered that adding relbar() will cause duplicate navigation
> bars on my local machine, and one on the remote server (why??).  I've
> also never had to use that function call before (why??).  Also, with
> that addition we can now see a navigation bar for the default navigation
> page, but not for any of our sphinx-translated pages in other languages
> (how to get that bar on those other pages?).   This is very confusing.
> Here is the ugly new layout.html
> 
>  {% extends "!layout.html" %}
> 
>   {% block relbar1 %}
> {{relbar() }}
> {{ super() }}
>   {% endblock %}
> 
>   {{ super() }}
>  {% endblock %}
> 
> 
> -jeff
> 
> 
> 
> On 2015-10-20 1:00 PM, Jeff McKenna wrote:
>> I have even cleaned it so it my layout.html file is bare bones, and the
>> relbar still doesn't show on that machine:
>>
>>   {% extends "!layout.html" %}
>>
>>{% block relbar1 %}
>>  {{ super() }}
>>{% endblock %}
>>
>>{{ super() }}
>>   {% endblock %}
>>
>> -jeff
>>
>>
>>
>>
>> On 2015-10-20 12:42 PM, Jeff McKenna wrote:
>>> Here is my layout,html contents (I don't see why relbar would be left
>>> out on some machines):
>>>
>>>{% extends "!layout.html" %}
>>>
>>>{% block relbar1 %}
>>>
>>>  (some stuff)
>>>
>>>{{ super() }}
>>>{% endblock %}
>>>
>>>
>>> -jeff
>>>
>>>
>>>
>>>
>>> On Tuesday, October 20, 2015 at 12:06:48 PM UTC-3, Luc Saffre wrote:
>>>
>>> Hi Jeff,
>>>
>>> thanks for asking. No, unfortunately I did not yet find a solution
>>> for
>>> this problem. Did you also use Takayuki's trick of adding a custom
>>> css
>>> rule? As the problem is just irritating and not fatal, I am still
>>> hoping
>>> for an idea or hint from this group before diving back into it.
>>>
>>> Luc
>>>
>>> On 20/10/15 17:48, Jeff McKenna wrote:
>>>  > On 2015-09-24 6:40 PM, Luc Saffre wrote:
>>>  >> Hi,
>>>  >>
>>>  >> I noticed that Sphinx no longer seems to generate the navigation
>>> bar
>>>  >> (with parent and previous|next links). I noticed this after
>>> moving to a
>>>  >> new machine, so there are a lot of details that might have
>>> possibly
>>>  >> changed. But I cannot find the reason.
>>>  >>
>>>  >> The problem is visible for example on this page:
>>>  >>
>>>  >> http://www.lino-framework.org/dev/index.html
>>> <http://www.lino-framework.org/dev/index.html>
>>>  >>
>>>  >> There is no navigation bar.
>>>  >>
>>>  >> All source files of this doctree can be browsed here:
>>>  >>
>>>  >> https://github.com/lsaffre/lino/tree/master/docs
>>> <https://github.com/lsaffre/lino/tree/master/docs>
>>>  >>
>>>  >> I am using Takayuki's trick of adding a custom css rule:
>>>  >>
>>>  >>div.related { display: block; }
>>>  >>
>>>  >> I tried with 1.3.1 and 1.3.0 (the current development version
>>> failed for
>>>  >> some complex reason), and versions <1.3 are no candidates
>>> since it
>>>  >> hasbgeen working with 1.3 some weeks ago.
>>>  >>
>>>  >> It seems that the relbar() nmacro defined in
>>> `themes/basic/layout.html`
>>>  >> gets never executed.
>>>  >>
>>>  >> I am stuck, and it is a bit sad because my mentioned document is
>>>  &

Re: [sphinx-users] navigation bar has disappeared

[Luc Saffre]

Yes, my site doesn't use translations. Yes, this is tricky. Did you try
changing your `site-packages/sphinx/themes/basic/layout.html` file for
debugging?

Luc

On 21/10/15 01:18, Jeff McKenna wrote:
> Glad my hack worked for you (I can see it at the top of your page now).
>  But in my case, it only appears for the default page, English
> (http://www.mapserver.org/).  By chance, your site doesn't use
> translations, right?  For some reason, my relbar() call is only being
> applied to the default language (if I click German for example, it
> disappears http://www.mapserver.org/de/index.html).  
> 
> Boy this is tricky,
> 
> -jeff
> 
> 
> On Tuesday, October 20, 2015 at 2:59:26 PM UTC-3, Luc Saffre wrote:
> 
> Hey cool! Thanks for sharing this! I can confirm this behaviour. I
> added
> these lines to my layout.html templates:
> 
> {% block relbar1 %}
> {{relbar() }}
> {{ super() }}
> {% endblock %}
> 
> {% block relbar2 %}
> {{relbar() }}
> {{ super() }}
> {% endblock %}
> 
> Looks indeed as if the relbar() macro no longer gets called by the
> default relbarN blocks.
> I don't see that duplicate navigation bar (probably because before I
> had
> no bar at all on all my doctrees).
> 
> I am using Sphinx 1.3.1 and Jinja2 version 2.8. Please verify your
> Jinja
> versions (the problem might be there).
> 
> My problem is fixed (though not in an elegant way).
> 
> Luc
> 
> 
> On 20/10/15 20:26, Jeff McKenna wrote:
> > I just discovered that adding relbar() will cause duplicate
> navigation
> > bars on my local machine, and one on the remote server (why??).  I've
> > also never had to use that function call before (why??).  Also, with
> > that addition we can now see a navigation bar for the default
> navigation
> > page, but not for any of our sphinx-translated pages in other
> languages
> > (how to get that bar on those other pages?).   This is very
> confusing.
> > Here is the ugly new layout.html
> >
> >  {% extends "!layout.html" %}
> >
> >   {% block relbar1 %}
> > {{relbar() }}
> > {{ super() }}
> >   {% endblock %}
> >
> >   {{ super() }}
> >  {% endblock %}
> >
> >
> > -jeff
> >
> >
> >
> > On 2015-10-20 1:00 PM, Jeff McKenna wrote:
> >> I have even cleaned it so it my layout.html file is bare bones,
> and the
> >> relbar still doesn't show on that machine:
> >>
> >>   {% extends "!layout.html" %}
> >>
> >>{% block relbar1 %}
> >>  {{ super() }}
> >>{% endblock %}
> >>
> >>{{ super() }}
> >>   {% endblock %}
> >>
> >> -jeff
> >>
> >>
> >>
> >>
> >> On 2015-10-20 12:42 PM, Jeff McKenna wrote:
> >>> Here is my layout,html contents (I don't see why relbar would be
> left
> >>> out on some machines):
> >>>
> >>>{% extends "!layout.html" %}
> >>>
> >>>{% block relbar1 %}
> >>>
> >>>  (some stuff)
> >>>
> >>>{{ super() }}
> >>>{% endblock %}
> >>>
> >>>
> >>> -jeff
> >>>
> >>>
> >>>
> >>>
> >>> On Tuesday, October 20, 2015 at 12:06:48 PM UTC-3, Luc Saffre
> wrote:
> >>>
> >>> Hi Jeff,
> >>>
> >>> thanks for asking. No, unfortunately I did not yet find a
> solution
> >>> for
> >>> this problem. Did you also use Takayuki's trick of adding a
> custom
> >>> css
> >>> rule? As the problem is just irritating and not fatal, I am
> still
> >>> hoping
> >>> for an idea or hint from this group before diving back into it.
> >>>
> >>> Luc
> >>>
> >>> On 20/10/15 17:48, Jeff McKenna wrote:
> >>>  > On 2015-09-24 6:40 PM, Luc Saffre wrote:
> >>>  >> Hi,
> >>>  >>
> >>>  >> I noticed that Sphinx no longer seems to generate the
> navigation
&

[sphinx-users] navigation bar has disappeared

[Luc Saffre]

Hi,

I noticed that Sphinx no longer seems to generate the navigation bar
(with parent and previous|next links). I noticed this after moving to a
new machine, so there are a lot of details that might have possibly
changed. But I cannot find the reason.

The problem is visible for example on this page:

  http://www.lino-framework.org/dev/index.html

There is no navigation bar.

All source files of this doctree can be browsed here:

  https://github.com/lsaffre/lino/tree/master/docs

I am using Takayuki's trick of adding a custom css rule:

  div.related { display: block; }

I tried with 1.3.1 and 1.3.0 (the current development version failed for
some complex reason), and versions <1.3 are no candidates since it
hasbgeen working with 1.3 some weeks ago.

It seems that the relbar() nmacro defined in `themes/basic/layout.html`
gets never executed.

I am stuck, and it is a bit sad because my mentioned document is
difficult to read without the navigation bar.

Any idea or hint?

Luc

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Creating printed, "folded" book?

[Luc Saffre]

Yes, but you must do it yourself. Basically you must add commands to
your Makefile. You should first generate a pdf file and then use some
tools as described here:

  http://www.peppertop.com/blog/?p=35

Luc

On 16/09/15 23:43, Eric Cozzi wrote:
> Can sphinx be used to create a printed, "folded" book or pamphlet? Where
> the printed pages each contain two, but not necessarily consecutive,
> pages, per side? 
> 
> Thanks,
> Eric
> 
> -- 
> 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 http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Absolute URLS + user defined root

[Luc Saffre]

Yann,

not sure whether this helps (it is for the html builder), but I use a
custom layout.html template with hard-coded absolute urls. For example here:
https://github.com/lsaffre/lino/blob/master/docs/.templates/layout.html

Currently I copy that layout.html to most of my doctrees and edit them.
To this more elegant, I would appreciate to have Sphinx's configuration
settings available in the template context. But AFAICS it is not
currently available:
http://sphinx-doc.org/templating.html#working-with-the-builtin-templates

For the json builder I am surprised that you need the absolute url in
the json output. Why can't the software that reads your json files
interprete these links?

Luc

On 05/07/15 00:44, Yann B. wrote:
 Hi,
 
 Is there a way to get absolute URLs in the generated HTML ? In my case I
 use the JSON builder and It's quite complicated to have links that works
 depending on whether the current URL has a trailing slash or not. I used
 to rewrite URLs at my app's router level, redirecting pages with missing
 trailing slashes, but I can't do that anymore.
 
 Right now a link to another document is like this: my/document. The
 documentation root on my website is /doc/, so I'd like the generated
 links to be like /doc/my/document/. Is there a way to achieve this ?
 
 Thanks,
 
 Yann
 
 -- 
 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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Re: defining reference label

[Luc Saffre]

Andrea,

maybe you can solve your use case using the `class` and
`attribute` directives. You can use these directives even if it is not
about a Python class.

Something like this::


  .. class:: AAA

This is an enumeration of bla bla...

.. attribute:: item1

To be used when bla bla

.. attribute:: item2

To be used when bla bla

And then you can refer to it as :attr:`AAA.item1`.

As an example, when I write :attr:`TradeTypes.sales` in my blog, then it
would link to
http://lino-framework.org/api/lino.modlib.ledger.choicelists#lino.modlib.ledger.choicelists.TradeTypes.sales.

That's admittedly not as lightweight as a bullet list, but when I had
this kind of situation, I was satisfied by the layout.

hth,
Luc

On 10/06/15 11:13, Andrea Cassioli wrote:
 Well,
 using sections and subsection is what I do now. 
 
 My use case is that I have some material that does not really deserve a
 section but perhaps a bullet list. I's like to point to that list
 entries, for instance
 .. _enumAAA
 
 Enumerarion AAA
 ---
 
 .. enumAAA.item1:
 
 * item1 : blah
 
 .. enumAAA.item2:
 
 * item2 : blah
 
 .. enumAAA.item3:
 
 * item3 : blah
 
 
 The I'like to write something like
 
 Please use :ref:`enumAAA.item1`, but I may want to use a different
 label, for instance upper case. 
 
 
 The point is that I generate part of the docs automatically and I may
 want to change the layout. The part of the docs I write by hand should
 be kept almost untouched.
 
 
 
 
 On Friday, June 5, 2015 at 11:16:10 AM UTC+2, Andrea Cassioli wrote:
 
 Hi,
 this may seems a stupid question, buthere it is!
 
 I would like to set some links around my docs in arbitrary position,
 i.e. not linked to sections. I would like to refer to them just by
 reference name and let the displayed text be defined along the
 label. For instance
 
 .. _`label linkname` 
 
 
 and somewhere else, possibly a different file, say
 
 
 Blah blah, :ref:`linkname`
 
 
 I would then expect to get
 
 Blah blah, label
 
 
 
 The reason is that some names and label docs may change in the
 future and I would like the docs to be robust. 
 
 Any ideas?
 
 -- 
 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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Re: defining reference label

[Luc Saffre]

Andrea,

can't you design your content in a way that it has a section header at
that entry point?  I mean if you want to write::


==
About foos
==

A foo is a blabla...

And also bla bla...

.. reftarget: foobla

And by the way also bla bla...


I'd suggest that you write


==
About foos
==

A foo is a blabla...

And also bla bla...

.. _reftarget:

Foo blabla
==

And by the way also bla bla...

I mean if I imagine myself reading a html page, then I'd find it
irritating to click a link and getting beamed to some arbitrary place
which does not even have section title.

Luc

On 08/06/15 16:39, Andrea Cassioli wrote:
 Hi,
 thank you for the reply.
 
 Actually I may have not been clear. My point is I would like to define a
 label in some arbitrary position along with the text to be displayed.
 Then the link should only use the label. 
 
 What you suggest would require me to specify the linkname, and this is
 exactly what I want avoid!
 
 Ideally, it will look like
 
 ```
 .. _linkname: label
 
 ```
 and somewhere else
 
 ```
 :ref:`linkname`
 ```
 
 
 the would be expanded showing `label` in the text. Exactly the way it
 works foe sections, but for arbitrary labels.
 
 But it seems it is not that easy without writing some directives myself.
 Maybe I should put a request-of-implementation out there.
 
 On Friday, June 5, 2015 at 11:16:10 AM UTC+2, Andrea Cassioli wrote:
 
 Hi,
 this may seems a stupid question, buthere it is!
 
 I would like to set some links around my docs in arbitrary position,
 i.e. not linked to sections. I would like to refer to them just by
 reference name and let the displayed text be defined along the
 label. For instance
 
 .. _`label linkname` 
 
 
 and somewhere else, possibly a different file, say
 
 
 Blah blah, :ref:`linkname`
 
 
 I would then expect to get
 
 Blah blah, label
 
 
 
 The reason is that some names and label docs may change in the
 future and I would like the docs to be robust. 
 
 Any ideas?
 
 -- 
 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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Link Company/Author name to Website in Copyright footer

[Luc Saffre]

Monami,

without hardcoding it in the CSS?

Do you know that you can override the templates? For me it seems an
acceptable task to use a custom layout.html when I want to fine-tune the
HTML output. Here is an example:

 https://github.com/lsaffre/lino/blob/master/docs/.templates/layout.html

And do you know that if you have a page copyright.rst (at the top of
the document tree), then the Copyright text will be clickable and lead
to that page.

Luc

On 21/05/15 10:09, Monami Bhattacharya wrote:
 Hi,
 
 Is there an easy way of hyperlinking the company or author name
 displayed in the HTML footer without hardcoding it in the CSS?
 
 The conf.py seems to furnish these details, but if one adds an href
 there, it is displayed as is, with the copyright text.
 
 |
 copyright =u'2015, a href=www.example.comNameGoesHere/a'
 |
 
 
 The theme.css seems to contain the directive, but I'm wondering if
 there's a way to do this without hardcoding it in there.
 
 |
 fa-copyright:before{content:}
 |
 
 
 In footer.html
 
 |
 divrole=contentinfop{%- if show_copyright %} {%- if
 hasdoc('copyright') %} {% trans path=pathto('copyright'),
 copyright=copyright|e %}copy; ahref={{ path }}Copyright/a{{
 copyright }}.{% endtrans %} {%- else %} {% trans copyright=copyright|e
 %}copy; Copyright {{ copyright }}.{% endtrans %} {%- endif %} {%- endif
 %} /div
 |
 
 Appreciate all inputs, thanks!
 M
 
 -- 
 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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Incorporating code into Sphinx

[Luc Saffre]

On 22/05/15 06:01, Anthony Pinter wrote:
 Is there a way to incorporate executable Python code into Sphinx? If
 not, is there a way to incorporate an API call and display the results
 (i.e. a live stock price)?

Anthony,

maybe you want the py2rst directive:

http://atelier.lino-framework.org/api/atelier.sphinxconf.insert_input.html

(Disclaimer: I am the author)

Luc

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Contact Form

[Luc Saffre]

Hi Monami,

On 05/05/15 13:16, Monami Bhattacharya wrote:
 Is it possible to add an interactive HTML Contact Us or Feedback
 form to a Sphinx generated static site? How? Expected to appear in the
 toctree same as any other topic/chapter. Am using the sphinx_rtd_theme.

I do this using a page `contact.rst` with a raw html directive as in
the following example (sorry for the user texts in German but I guess
that you can imagine what they mean). This requires of course a
formmailer script which processes the submitted form data, and this
script must be implemented separately at the URL specified at FORM
action=...

Kontakt
===

.. raw:: html


  script type=text/javascript
  function checkForm() {
document.calledfrom.value=window.location.href;
if (document.feedback.comment.value == ) {
  alert('Kommentar' darf nicht leer sein!);
  document.feedback.comment.focus();
  return false;
}
if (document.feedback.name.value == ) {
  alert('Ihr Name' darf nicht leer sein!);
  document.feedback.name.focus();
  return false;
}
if (document.feedback.email.value == ) {
  alert('Ihre E-Mail-Adresse' darf nicht leer sein!);
  document.feedback.email.focus();
  return false;
}
  }
  /script

  FORM name=feedback
  action=http://www.example.com/formmail/form.py/email
  method=post onsubmit=return checkForm()

  h41. Obligatorische Angaben/h4

  TABLE class=form

  TR
  TDPKommentar:/p/TD
  TDTEXTAREA name=comment rows=10 cols=40/TEXTAREA
  /TD/TR

  TR TDIhr Name:/TD
  TDINPUT class=searchbox size=30 name=name /TD/TR

  TR
  TDIhre E-Mail-Adresse:/TD
  TDINPUT class=searchbox size=30 name=email

  /TD/TR

  /TABLE

  h42. Fakultative Angaben/h4

  TABLE class=form
  TR TDPostadresse/TDTD
  TEXTAREA name=r_postadresse rows=3 cols=40/TEXTAREA
  /TD/TR

  TR TDTelefon:/TDTD

  INPUT class=searchbox size=30 name=f_phone
  /TD/TR

  TR TDSkypename:/TDTD
  INPUT class=searchbox size=30 name=f_skype
  /TD/TR

  /TABLE

  INPUT type=hidden name=calledfrom
value=http://www.example.com/contact.html;
  INPUT type=hidden name=_response_ok
value=http://www.example.com/contact-ok.html;
  INPUT type=hidden name=_recipient
value=i...@example.com

  INPUT class=searchbtn type=submit
 value=Senden
 name=__
  INPUT class=searchbtn type=reset
 value=Louml;schen
 name=__

  /FORM


I also have a page contact-ok.rst to be displayed upon success
(specified in the hidden input named _response_ok) with this content:

:orphan: http://sphinx.pocoo.org/markup/misc.html#file-wide-metadata

Kontakt - OK


Ihre Rückmeldung wurde abgeschickt,
und wir werden sie so schnell wie möglich beantworten.

HTH,
Luc

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] How to support both sphinx 1.2.2 and 1.3.1 in conf.py?

[Luc Saffre]

I have something like this in my conf.py::

  import os
  on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
  if on_rtd:
  ...
  else:
  ...

This is documented here:

  http://docs.readthedocs.org/en/latest/faq.html

hth,
Luc


On 14/04/15 10:09, Alexander Belchenko wrote:
 Hi,
 
 I need help on the subject.
 I'd like to explain. Recently I've installed sphinx with `pip install
 sphinx` and got version 1.3.1. I should admit that I haven't been using
 Sphinx doc for 2 years, so I don't even remeber which latest version I
 used earlier. Anyway, the version number should not matter for me, but
 in fact it does matter. And I should say that I'm not very happy with my
 situation.
 
 As I've discovered your version 1.3.1 requires new option in conf.py:
 
 html_theme = 'classic'
 
 in order to get the same look as in older versions. That was OK until I
 tried to publish my docs to readthedocs.org site.
 
 Probably you had very important reasons to change the defaults, although
 I don't understand them. Why not using classic as default theme?
 
 Now the bad part of the story: readthedocs tried to build documentation
 with sphinx 1.2.2. I don't know why they're using this version.
 But result is quite disappointing: html docs didn't build. Here is
 excerpt from the failed build log:
 --
 html
 -
 Making output directory...
 Running Sphinx v1.2.2
 loading translations [en]... done
 
 Build Standard Error
 
 html
 -
 Traceback (most recent call last):
   File
 /home/docs/checkouts/readthedocs.org/user_builds/python-intelhex/envs/2.0/local/lib/python2.7/site-packages/sphinx/cmdline.py,
 line 253, in main
 warningiserror, tags, verbosity, parallel)
   File
 /home/docs/checkouts/readthedocs.org/user_builds/python-intelhex/envs/2.0/local/lib/python2.7/site-packages/sphinx/application.py,
 line 139, in __init__
 self._init_builder(buildername)
   File
 /home/docs/checkouts/readthedocs.org/user_builds/python-intelhex/envs/2.0/local/lib/python2.7/site-packages/sphinx/application.py,
 line 200, in _init_builder
 self.builder = builderclass(self)
   File
 /home/docs/checkouts/readthedocs.org/user_builds/python-intelhex/envs/2.0/local/lib/python2.7/site-packages/sphinx/builders/__init__.py,
 line 68, in __init__
 self.init()
   File
 /home/docs/checkouts/readthedocs.org/user_builds/python-intelhex/envs/2.0/local/lib/python2.7/site-packages/readthedocs_ext/readthedocs.py,
 line 77, in init
 StandaloneHTMLBuilder.init(self)
   File
 /home/docs/checkouts/readthedocs.org/user_builds/python-intelhex/envs/2.0/local/lib/python2.7/site-packages/sphinx/builders/html.py,
 line 108, in init
 self.init_templates()
   File
 /home/docs/checkouts/readthedocs.org/user_builds/python-intelhex/envs/2.0/local/lib/python2.7/site-packages/sphinx/builders/html.py,
 line 143, in init_templates
 self.theme = Theme(themename)
   File
 /home/docs/checkouts/readthedocs.org/user_builds/python-intelhex/envs/2.0/local/lib/python2.7/site-packages/sphinx/theming.py,
 line 82, in __init__
 '(missing theme.conf?)' % name)
 ThemeError: no theme named 'classic' found (missing theme.conf?)
 
 Theme error:
 no theme named 'classic' found (missing theme.conf?)
 ---
 
 I can reproduce this error locally with sphinx 1.2.2.
 
 After I removed html_theme='classic' from conf.py - readthedocs can
 build my docs.
 
 So far I've put -D html_theme=classic to Makefile but I don't like this
 hack, esp. because it does not play well with sphinx-autobuild.
 
 So, I'd like to know, is there any way to put some conditional to
 conf.py itself to check whether it's building with sphinx 1.3.1 and
 later to put required option, something like:
 
 if sphinx_version = '1.3.1':
 html_theme = 'classic'
 
 I hope it's possible.
 
 -- 
 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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Pure API reference browser?

[Luc Saffre]

On 18/03/15 17:25, Eric Holscher wrote:
 The main problem with this is that it is using Python explicitly. I'm
 hoping to have something that will work with the Sphinx representation
 of a domain, so that it would work across all the languages that Sphinx
 supports.
 
 I'm hoping to be able to build Sphinx support for other languages that
 are first class, but so much of the existing tooling is Python-specific,
 and requires importing Python code, that it makes it not reusable.
 
 I'll look at bit more into the autosummary tooling, but I know autodoc
 in general is very Python specific, and doesn't actually use Sphinx's
 domain abstractions in a real way.

Oh yes, indeed. AFAICS autodoc and autosummary are designed to work only
for Python code. I didn't even realize that you actually meant to
analyze other code.

Your idea of writing an autodoc for other languages sounds
interesting. (though i am probably not going to need it because i am in
the (un)fortunate situation of writing almost only in Python ;-)

Luc

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Pure API reference browser?

[Luc Saffre]

Hi Eric,

your question looks as if you are looking for autosummary:

  http://sphinx-doc.org/latest/ext/autosummary.html

Usage example:

  http://lino-framework.org/api/index.html
  https://github.com/lsaffre/lino/tree/master/docs

Luc


On 18/03/15 00:39, Eric Holscher wrote:
 Hi,
 
 Does anyone know if there exists a way to get Sphinx to output a
 standard javadoc style API browser for a domain? I mostly just want a
 way to display all of the existing classes and methods, in a standard
 format with a basic hierarchy. All the data is there in the domain, I
 guess I'm more just wanting something like:
 
 api/index.rst:
 
 .. autopackage:: mypackage
 
 Then this will generate a full set of HTML pages that is generated from
 that package. Instead of me having to have something like:
 
 api/index.rst
 api/class1.rst
 api/class2.rst
 
 I just want them all to be outputted at once. I know that sphinx-autogen
 exists, but I want it to just be a comprehensive set of all of a module
 by default.
 
 I'll probably end up building this if one doesn't already exist. Even
 pointers at half-finished or attempts along these lines would be much
 appreciated.
 
 Cheers,
 Eric
 
 -- 
 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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] ABlog for blogging with Sphinx

[Luc Saffre]

On 22/07/14 16:59, yarko wrote:
 
 Your first link links pretty good on mobile / phone.   Just curious -
 did you start with a stock theme or site?

Yes, Alabaster by Jeff Forcier:

https://github.com/bitprophet/alabaster

Luc

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] ABlog for blogging with Sphinx

[Luc Saffre]

Hi Ahmet,

your ablog is really cool! Sorry for my late reply. I made two prototype
websites using it:

http://www.vana-vigala.ee/
http://luc.saffre-rumma.net/

One serious missing feature is internationalization. I have created an
issue on github for that:
https://github.com/abakan/ablog/issues/3

Luc


On 19/05/14 08:58, Ahmet Bakan wrote:
 Hi Everyone,
 
 I have developed a Sphinx extension for
 blogging: http://ablog.readthedocs.org/
 You can easily add blogging and RSS feeds to any project.
 I would love to hear your thoughts,
 
 Best,
 Ahmet
 
 -- 
 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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Searching in 600+ files

[Luc Saffre]

On 12/06/14 21:50, Jan Ulrich Hasecke wrote:
 Has anyone used Sphinx with more than 600 files?

It seems that my biggest Sphinx site has about 1300 files:

  http://lino-framework.org

Is there an easy way to count the pages in a tree? Here is how I did it:

  $ find docs -name '*.rst' | wc -l
  1967

(And then I subtract about 600 from that number because I have an
`exclude_patterns`)

And I cannot complain that the quick search function on that site is slow.

Luc

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] apidoc output format

[Luc Saffre]

Strange indeed... Do the following commands describe my environment?
(issued in the top directory of my copy)

$ hg pull -u
pulling from https://bitbucket.org/birkenfeld/sphinx
searching for changes
no changes found
$ hg tip
changeset:   4717:6af68dfb4df4
tag: tip
user:shimizukawa shimizuk...@gmail.com
date:Mon May 05 16:21:32 2014 +0900
summary: update CHANGES for string length of the websupport db schema.

Luc

On 08/05/14 17:51, Takayuki Shimizukawa wrote:
 Hi Luc,
 
 but here is again a patch, against the newest version.
 
 Strange... attached patch's difference is already applied at:
 https://bitbucket.org/birkenfeld/sphinx/commits/de57208a8
 Please re-confirm the your environment if you have a chance, or please
 send me a smallest sample to reproduce the issue.
 
 Thanks,
 --
 Takayuki SHIMIZUKAWA
 http://about.me/shimizukawa
 
 
 2014-05-08 15:33 GMT+09:00 Luc Saffre luc.saf...@gmail.com:
 Hi Takayuki,

 you wrote that you added that newline, and my first tests confirmed
 it... but in another doctree I had the problem again and then saw that
 this additional newline is still missing. The problem comes when
 `modulefirst` is True and the `__init__.py` file has no docstring. I
 don't know what went wrong there, but here is again a patch, against the
 newest version.

 Luc


 On 05/05/14 06:32, Takayuki Shimizukawa wrote:
 Hi,

 Thanks for your propose.
 The pull request #236 and suggested append-newline code has been
 merged into 'default' branch.

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


 2014-04-23 15:56 GMT+09:00 Luc Saffre luc.saf...@gmail.com:
 On 20/04/14 03:12, Wes Turner wrote:

 Pull
 Request: 
 https://bitbucket.org/birkenfeld/sphinx/pull-request/236/1456-apidoc-add-a-m-option-to-put-module/diff


 Wes, here is a little bugfix. Add an additional empty line after the
 automodule directive. Otherwise packages with empty docstring caused a
 syntax error.

 Luc

 $ hg diff sphinx/apidoc.py
 diff -r c171d4eef221 sphinx/apidoc.py
 --- a/sphinx/apidoc.py  Sat Apr 19 19:08:41 2014 -0500
 +++ b/sphinx/apidoc.py  Wed Apr 23 09:51:40 2014 +0300
 @@ -98,6 +98,7 @@

  if opts.modulefirst:
  text += format_directive(subroot, master_package)
 +text += '\n'

  # build a list of directories that are szvpackages (contain an
 INITPY file)
  subs = [sub for sub in subs if path.isfile(path.join(root, sub,
 INITPY))]


 --
 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 http://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 http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] apidoc output format

[Luc Saffre]

I pulled the default branch and ran a build: seems to work fine.
Thank you both;-)

Luc

On 05/05/14 14:38, Wes Turner wrote:
 Thank you both!
 
 Wes Turner
 
 On May 4, 2014 10:32 PM, Takayuki Shimizukawa shimizuk...@gmail.com
 mailto:shimizuk...@gmail.com wrote:
 
 Hi,
 
 Thanks for your propose.
 The pull request #236 and suggested append-newline code has been
 merged into 'default' branch.
 
 Thanks!
 --
 Takayuki SHIMIZUKAWA
 http://about.me/shimizukawa
 
 
 2014-04-23 15:56 GMT+09:00 Luc Saffre luc.saf...@gmail.com
 mailto:luc.saf...@gmail.com:
  On 20/04/14 03:12, Wes Turner wrote:
 
  Pull
  Request:
 
 https://bitbucket.org/birkenfeld/sphinx/pull-request/236/1456-apidoc-add-a-m-option-to-put-module/diff
 
 
  Wes, here is a little bugfix. Add an additional empty line after the
  automodule directive. Otherwise packages with empty docstring caused a
  syntax error.
 
  Luc
 
  $ hg diff sphinx/apidoc.py
  diff -r c171d4eef221 sphinx/apidoc.py
  --- a/sphinx/apidoc.py  Sat Apr 19 19:08:41 2014 -0500
  +++ b/sphinx/apidoc.py  Wed Apr 23 09:51:40 2014 +0300
  @@ -98,6 +98,7 @@
 
   if opts.modulefirst:
   text += format_directive(subroot, master_package)
  +text += '\n'
 
   # build a list of directories that are szvpackages (contain an
  INITPY file)
   subs = [sub for sub in subs if path.isfile(path.join(root, sub,
  INITPY))]
 
 
  --
  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
 mailto:sphinx-users%2bunsubscr...@googlegroups.com.
  To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
  Visit this group at http://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 a topic in
 the Google Groups sphinx-users group.
 To unsubscribe from this topic, visit
 https://groups.google.com/d/topic/sphinx-users/Bm4w7OQcWYM/unsubscribe.
 To unsubscribe from this group and all its topics, send an email to
 sphinx-users+unsubscr...@googlegroups.com
 mailto:sphinx-users%2bunsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Directive for defining an 'abstract'/'summary' in a source file and displaying in toctree?

[Luc Saffre]

Yes, that would be indeed a nice thing to have. I've been dreaming of it
and looking around, but didn't yet find anything similar. If I had more
time, then I would probably extend my directory directive and write it
myself:
http://atelier.lino-framework.org/api/atelier.sphinxconf.dirtables.html

Luc

On 24/04/14 16:38, Neil K wrote:
 I have had a good hunt around looking for the ability to define per file
 an 'abstract' / 'summary' that I can then have displayed in a toctree
 but have come up blank. What I am looking for is something akin to the
 autosummary/docstring approach but not quite. Does this exist? Have I
 missed it somewhere? Maybe I will have to create my own directive but
 thought I would ask first.
 
 To be clear about what I am looking for I have a outlined an example below.
 
 Lets say I have a file called white_paper_001.rst that looks like this -
 they part being the abstract is defined so that it can be used:
 
 ===
 White Paper 001
 ===
 
 *.. abstract::*
This white paper explains the relationship between X and Y.
 
 Body text will go here 
 
 
 In my index.rst I would have something like this -  identifying that I
 want the abstract included in the listing in much the same way as
 the :titlesonly:option tells sphinx to display the titles:
 
 
 White Papers
 
 
 Contents:
 
 .. toctree::
 :glob:
 
 *:abstract:*
 
 
 white_papers/*
 
 
 Ideally I would then get something like the following - the key here is
 that the abstract is sourced from the file itself rather than keyed in
 independently on index.rst:
 
 *White Papers*
 
  
 
 _White Paper 001_
 
 This white paper explains the relationship between X and Y. 
 
   
 
 _White Paper 002_
 
 This white paper explains the key concepts around ABC. 
 
 -- 
 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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] apidoc output format

[Luc Saffre]

On 20/04/14 03:12, Wes Turner wrote:
 
 Issue:
 https://bitbucket.org/birkenfeld/sphinx/issue/1456/apidoc-add-a-m-option-to-put-module
 
 Pull
 Request: 
 https://bitbucket.org/birkenfeld/sphinx/pull-request/236/1456-apidoc-add-a-m-option-to-put-module/diff
  

Great! I tried this as follows:

Made hg pull -u in my local copy of the repository, but (of course)
your pull request isn't yet in default branch.

$ hg pull -u https://bitbucket.org/westurner/sphinx/\
  branch/apidoc_output_order
searching for changes
adding changesets
adding manifests
adding file changes
added 2 changesets with 1 changes to 1 files (+1 heads)
0 files updated, 0 files merged, 0 files removed, 0 files unresolved

$ hg update apidoc_output_order

So I can confirm that the patch works (for me).

And I confirm that for me this setting seems the natural way.  I don't
claim to be representative, but the lack of this option has always be a
kind of obstacle for me when trying to give a digestable structure to my
documentation.  Now that this setting is getting into Sphinx, I can
finally move into this direction. I updated the following page as a
proof of my claim:

  http://lino-framework.org/api/lino.mixins.html

Thanks, Wes for integrating this.

Luc

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

Re: [sphinx-users] Suppress warnings about documents not included in a toctree

[Luc Saffre]

Hi Richard,

did you try to add a second toctree with :hidden:?

.. toctree::
   webpage1
   webpage2

.. toctree::
   :hidden:
   manpage


Luc

On 04/03/14 15:59, Richard Dymond wrote:
 My project has HTML documentation and man pages that I build with
 Sphinx. I'd like to place the source files for both the HTML docs and
 the man pages in the same source tree, but when I do that, I get
 warnings when I do 'make html' about the man page source files not being
 included in any toctree. Is there any way to suppress those warnings?
 
 I've tried adding the man page source filenames to exclude_patterns in
 conf.py, which does prevent the warnings, but also prevents the man
 pages from building. I don't want to place the man page source files in
 a toctree, because I don't want the man pages appearing in the HTML docs.
 
 I notice that Sphinx itself has the man page source files in the same
 source tree as the other source files, and 'make html' produces no
 warnings, even though the man page source files are not included in any
 toctree (as far as I can see). How does that work?
 
 Richard
 
 -- 
 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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://groups.google.com/group/sphinx-users.
 For more options, visit https://groups.google.com/groups/opt_out.

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/groups/opt_out.

Re: [sphinx-users] Is sphinx-build extremely dangerous? Or is it just me?

[Luc Saffre]

Thanks for reporting this. To be more precise, it is `sphinx-apidoc
http://sphinx-doc.org/invocation.html#invocation-of-sphinx-apidoc`_
who scans the filesystem and finds every Python module, writing Sphinx
source files. You must then run sphinx-build with `sphinx.ext.autodoc
http://sphinx-doc.org/ext/autodoc.html`_ enabled to actually import
all those modules. I suggest to add a warning about this possible
pitfall on both documentation pages.

Luc


On 04/03/14 16:09, Dan Harasty wrote:
 I'm new to Sphinx, but a seasoned Python programmer.  I'm working
 through the Sphinx tutorials, and I may have by sheer luck barely
 avoided a disaster.  Please: someone tell me if I'm being over dramatic,
 and calm this Sphinx-noob down.
 
 I'm so new, I'm not even really sure which part of Sphinx calls which,
 and which is exhibiting the [what I consider] extremely dangerous
 behavior: sphinx-build? sphinx-apidoc? make?  So in my ignorance, I'll
 just attribute all to sphinx-build.
 
 It seems that sphinx-build imports every Python file it finds in the
 directory it is pointed to.  But of course, it can't distinguish a true
 module
 (reusable code that performs no side-effects until functions are
 invoked) from a script (code invoke to do something).  It can't do
 this because that distinction is purely in the developer's head, not in
 Python or Python files themselves.
 
 Therein is -- what I consider -- the extreme danger.  In our system, we
 occasionally have maintenance scripts sitting in the directories with
 the modules.  Script that do minor stuff like, oh, delete important
 system logs, kick off long-running (multi-hour) table generation
 routines, or alter production tables, or even drop entire databases.  
 
 Imagine my panic when running sphinx-build for the first time, and I
 realize by the output that EVERYTHING is being imported... which means
 everything is being executed.  Did I leave any scripts in a state where
 they are deleting important files or dropping databases?  Are any of
 those configured to execute against our production system???
 
 Apparently, by sheer luck, no script was configured so as to produce an
 irrecoverable side effect, and I think my system escaped unscathed.
 
 But it could easily have happened.
 
 Once my blood pressure returned to normal and my panic subsided, I went
 back to the tutorial docs, looking for an explanation that ALL files
 would actually be imported/executed. I didn't see that.  I looked for a
 warning: if any of your modules or scripts in the tree perform side
 effects, put all that code in an if __name___=='__main__' block, or
 put ::sphinx-ignore-this-file as a comment somewhere in the file..  I
 didn't see that.
 
 Did I miss that?
 
 Has anyone considered how dangerous it is to execute EVERY PYTHON FILE
 in a large directory without proper warning (from Sphinx) and thorough
 code review (by the developer)?
 
 I guess I expected Sphinx would do its work by a simple lexical analysis
 of the Python files... and not actually import/execute them.  I admit:
 the docs (the tutorials that I've read so far) don't SAY that.  But they
 also don't say all will be imported/executed... which should be a VERY
 BIG caveat/warning in the tutorials.
 
 I love how the Sphinx docs look, and I'd like to use the system for my
 project and my team... But I need to have a rock solid way to make sure
 that the documentation build doesn't start trashing my operational
 system by executing scripts that had no intention of running or even
 have anything useful to be documented in them.
 
 
 -- 
 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
 mailto:sphinx-users+unsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://groups.google.com/group/sphinx-users.
 For more options, visit https://groups.google.com/groups/opt_out.

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/groups/opt_out.

Re: [sphinx-users] Sphinx 1.2.2 released

[Luc Saffre]

On 03/03/14 12:03, Georg Brandl wrote:
 Am 03.03.2014 04:40, schrieb Luc Saffre:
 On 02/03/14 19:05, Georg Brandl wrote:
 Am 02.03.2014 17:33, schrieb Luc Saffre:
 Strange.  Is there a template_bridge setting in your conf.py?  (I didn't 
 see
 one at a glance.)

 No.

 I considered trying to reproduce this problem in a simpler context, but
 this would take more time. I guess that it has to do with the fact that
 I use from __future__ import unicode_literals and/or execfile.
 
 The unicode_literals would do it, yes.  I wonder why it's new in 1.2.2 though;
 the code reading setups hasn't been updated inbetween.

Oops, sorry, Sphinx was innocent, the problem was in my own code. And
BTW I *did* set a template_bridge. The problem reappeared with the new
version because I had fixed it already in my copy of the previous
version without telling anybody about it. Had to rediscover all this.

Now I fixed my code and updated the docs for my atelier.sphinxconf package:

http://atelier.lino-framework.org/api/atelier.sphinxconf.html

Luc

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/groups/opt_out.

Re: [sphinx-users] Sphinx 1.2.2 released

[Luc Saffre]

On 02/03/14 09:51, Georg Brandl wrote:
 I'm delighted to announce the release of Sphinx 1.2.2, now available on
 the Python package index at http://pypi.python.org/pypi/Sphinx.

Thanks for your work, Georg!

I got the traceback below for build html after upgrading from 1.2.1 to
1.2.2.
My source files are here:
https://github.com/lsaffre/lino/tree/master/docs
I tried also after cleaning the doctree files, without success.

Any hints?

Luc

# Sphinx version: 1.2.2
# Python version: 2.7.4
# Docutils version: 0.11 release
# Jinja2 version: 2.7.2
# Loaded extensions:
Traceback (most recent call last):
  File
/home/luc/pythonenvs/py27/local/lib/python2.7/site-packages/sphinx/cmdline.py,
line 253, in main
warningiserror, tags, verbosity, parallel)
  File
/home/luc/pythonenvs/py27/local/lib/python2.7/site-packages/sphinx/application.py,
line 139, in __init__
self._init_builder(buildername)
  File
/home/luc/pythonenvs/py27/local/lib/python2.7/site-packages/sphinx/application.py,
line 200, in _init_builder
self.builder = builderclass(self)
  File
/home/luc/pythonenvs/py27/local/lib/python2.7/site-packages/sphinx/builders/__init__.py,
line 68, in __init__
self.init()
  File
/home/luc/pythonenvs/py27/local/lib/python2.7/site-packages/sphinx/builders/html.py,
line 108, in init
self.init_templates()
  File
/home/luc/pythonenvs/py27/local/lib/python2.7/site-packages/sphinx/builders/html.py,
line 145, in init_templates
self.create_template_bridge()
  File
/home/luc/pythonenvs/py27/local/lib/python2.7/site-packages/sphinx/builders/__init__.py,
line 81, in create_template_bridge
self.config.template_bridge, 'template_bridge setting')()
  File
/home/luc/pythonenvs/py27/local/lib/python2.7/site-packages/sphinx/application.py,
line 357, in import_object
return getattr(__import__(module, None, None, [name]), name)
TypeError: Item in ``from list'' not a string

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/groups/opt_out.

Re: [sphinx-users] How to use Sphinx as a general purpose text renderer?

[Luc Saffre]

On 12/02/14 12:46, Leo wrote:

 Looking from the other angle, I am intrigued by how you prevent Sphinx
 from displaying a link to the source at the bottom of your nice
 cycling website. Probably one can also get rid of the search field,
 the Next and Previous links etc. This type of knowledge could help
 tweak the Hieroglyph or Landslide generated slides. The Sphinx
 tutorial understandably assumes some HTML and CSS knowledge which I'd
 have to acquire first. Any hint where to start / what Sphinx templates
 etc. to modify?

Some hints:

Try to create a `layout.html` in your `.templates` directory which
overrides the default Sphinx footer block:

{% extends !layout.html %}
{%- block footer %}
div class=footer
My footer
/div
{%- endblock %}

Inspect the following files:

/sphinx/themes/default/layout.html
/sphinx/themes/basic/layout.html

Read these docs:
http://sphinx-doc.org/templating.html
http://jinja.pocoo.org/docs/templates/

Enjoy!
Luc

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/groups/opt_out.

Re: [sphinx-users] apidoc output format

[Luc Saffre]

Yes, de gustibus non est disputandum, but since it seems not trivial to
make this choice configurable, we might analyze a bit deeper and try to
find out *why* our preferences differ. If we get to some consensus, this
would add knowledge to Sphinx. My two cents to this discussion are then:
I think my way is better in packages with lots of subpackages. For
example (I didn't verify but I guess that) the documentation for
Python's xml package had to be done manually because current apidoc
output simply would not be readable:
http://docs.python.org/3/library/xml.html

Luc

On 10/01/14 18:32, Kevin Horn wrote:
 I have to say that I prefer it the way it is, rather than the way you've
 done it.
 
 I also can't imagine why you like your way better, but I guess that's
 why we're different people. :)
 
 I might be nice to have it configurable though, if it doesn't introduce
 too much complexity into the code.
 
 
 On Fri, Jan 10, 2014 at 6:15 AM, Luc Saffre luc.saf...@gmail.com
 mailto:luc.saf...@gmail.com wrote:
 
 Hi all,
 
 I made a little change to apidoc.py which I'd like to share here. I
 didn't like the fact that apidoc generates, in the main module of a
 package, first the sections Submodules and Subpackages and only then
 the Module contents. I prefer to have the module contents (without
 section header) at the beginning of the file, followed only then by the
 packages.
 
 In file apidoc.py, lines 91ff, function create_package_file, I moved the
 following two lines towards the beginning (just after the ``text =
 format_heading(1, '%s package' ...`` line::
 
 # text += format_heading(2, 'Module contents')
 text += format_directive(subroot, master_package)
 
 and after these lines I insert another blank line to the output::
 
 text += '\n\n'
 
 Here is an example output generated using these changes:
 http://lino-framework.org/api/lino.utils.html
 
 For me this way is much better. I don't imagine how somebody might
 prefer it the other way. But since this part of the apidoc output cannot
 easily be made configurable, we need to discuss here whether this new
 format might be acceptable for everybody. I must say that I use the
 `--separate` option, and that I don't claim to have made very deep
 investigations.
 
 What do other people think about this?
 
 Luc
 
 --
 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
 mailto:sphinx-users%2bunsubscr...@googlegroups.com.
 To post to this group, send email to sphinx-users@googlegroups.com
 mailto:sphinx-users@googlegroups.com.
 Visit this group at http://groups.google.com/group/sphinx-users.
 For more options, visit https://groups.google.com/groups/opt_out.
 
 
 
 
 -- 
 --
 Kevin Horn
 
 -- 
 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 http://groups.google.com/group/sphinx-users.
 For more options, visit https://groups.google.com/groups/opt_out.

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/groups/opt_out.

Re: [sphinx-users] pyRestTable 2014-02 released

[Luc Saffre]

Wow, telepathy! Your work looks very similar to what I wrote:

http://atelier.lino-framework.org/api/atelier.rstgen.html

Luc

On 08/02/14 22:16, Pete wrote:
 Announcing a small package that will generate a reST-formatted table
 from Python.
 
 The code is available for installation by pip or easy_install as well as
 from github
 (https://github.com/prjemian/pyRestTable/tarball/2014-02)
 
 See https://github.com/prjemian/pyRestTable for the source and the brief
 documentation.
 
 Pete
 
 -- 
 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 http://groups.google.com/group/sphinx-users.
 For more options, visit https://groups.google.com/groups/opt_out.

-- 
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 http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/groups/opt_out.

[sphinx-users] enhancement suggestion for linkcheck

[Luc Saffre]

Hi,

I suggest that linkcheck also checks external links to local URI's by 
verifying if the referred file exists. I use Sphinx to maintain 
http://www.vor-cycling.be/ which has lots of such links, and for me it 
is important to test them. I got that working for me with the following 
change in linkcheck.py:



def check():
# check for various conditions without bothering the network
if len(uri) == 0 or uri[0] == '#' or \
   uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:':
return 'unchecked', ''
elif not (uri[0:5] == 'http:' or uri[0:6] == 'https:'):
#~ return 'local', '' # LINE REPLACED BY THE FOLLOWING LINES
filename = path.abspath(path.join(self.outdir,docname,'..',uri))
if path.exists(filename):
return 'working', ''
else:
return 'broken', 'File %s does not exist.' % filename


Luc

--
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 http://groups.google.com/group/sphinx-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

[sphinx-users] unsupported build info format in .buildinfo

[Luc Saffre]

Hi all,

here are my two cents for a subtle optimization to Sphinx.

I sometimes had the following Sphinx warnings::

  WARNING: unsupported build info format in 
u'/home/luc/hgwork/welfare/docs/.build/.buildinfo', building all


Which disturbed me because it stopped the build
(because I have -W option turned on and want it to stay like this).

This invalid `.buildinfo` file contained::

# Sphinx build info version 1
# This file hashes the configuration used when building these 
files. When it is not found, a full rebuild will be done.

config:
tags:

It is indeed not normal to have this file exist with empty entries.
Possible that this comes because I use complex configurations.
But still it was Sphinx herself who generated this file and now
she complains about the content. That's not correct!
Here is the responsible code in `/sphinx/builders/html.py`::

try:
fp = open(path.join(self.outdir, '.buildinfo'))
try:
version = fp.readline()
if version.rstrip() != '# Sphinx build info version 1':
raise ValueError
fp.readline()  # skip commentary
cfg, old_config_hash = fp.readline().strip().split(': ')
if cfg != 'config':
raise ValueError
tag, old_tags_hash = fp.readline().strip().split(': ')
if tag != 'tags':
raise ValueError
finally:
fp.close()
except ValueError:
self.warn('unsupported build info format in %r, building all' %
  path.join(self.outdir, '.buildinfo'))
except Exception:
pass

A principal problem with this code is that it uses the
standard exception `ValueError` to handle a custom problem.
It's a mousetrap, and my concrete case of invalid build file
makes Sphinx step into this trap.
In fact (AFAICS) the author wants Sphinx to warn only in those
special cases and to silently ignore (without any warning)
any really invalid .buildinfo file.
So I suggest to replace ValueError by a custom exception InvalidInfo::

class InvalidInfo(Exception):
pass

try:
fp = open(path.join(self.outdir, '.buildinfo'))
try:
version = fp.readline()
if version.rstrip() != '# Sphinx build info version 1':
raise InvalidInfo
fp.readline()  # skip commentary
cfg, old_config_hash = fp.readline().strip().split(': ')
if cfg != 'config':
raise InvalidInfo
tag, old_tags_hash = fp.readline().strip().split(': ')
if tag != 'tags':
raise InvalidInfo
finally:
fp.close()
except InvalidInfo:
self.warn('unsupported build info format in %r, building all' %
  path.join(self.outdir, '.buildinfo'))
except Exception:
pass

Luc

--
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 http://groups.google.com/group/sphinx-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

Re: [sphinx-users] Re: Cannot embed stylesheet messages

[Luc Saffre]

On 04/16/2013 09:52 AM, Guenter Milde wrote:

On 2013-04-12, Luc Saffre wrote:


the new docutils version doesn't solve the problem, the message has just
become more short:



partial node:: (ERROR/3) Cannot embed stylesheet 'html4css1.css': No
such file or directory.



Otherwise it is still there, and it still doesn't cause any harm except
disturbing the output of my build.


The harm is subtle: missing standard formatting without the CSS rules in
the standard layout file. The difference might be almost invisible
depending on whether the document(s) contain construct relying on CSS
styling. (You may try to view, e.g., the functional test output files in
original form and with the stylesheet links removed to see the difference.)

...


I use Sphinx 1.2b1 and docutils 0.10, both installed using pip in a
virtualenv, and I get a lot of error messages when I build my Sphinx
docs:



partial node:: (ERROR/3) Cannot embed stylesheet
'../../../pythonenvs/py27/local/lib/python2.7/site-packages/docutils/writers/html4css1/html4css1.css':



No such file or directory.



It looks as if the substring /local in the above filename is too much.
I do have a file named
`/home/luc/pythonenvs/py27/lib/python2.7/site-packages/docutils/writers/html4css1/html4css1.css`



(without the /local)


Do you have a directory /pythonenvs/py27/local?
If so, what is in it?


Oops, my statement was wrong. Thank your for asking. Yes I do have a 
local directory, and it contains links to the corresponding non-local 
directories, and both paths (with and without the local) point to the 
file.


So I now guess that the prefix ../../../ is wrong.


Both, the release version and the repository version expect the standard
stylesheet in the same directory as the writer
(.../docutils/writers/html4css1). If you create a custom local writer, you
need to either copy or symlink the html4css4.css file or adapt the logic
that sets the stylesheet path.


No, I don't use a custom local writer.

Looking at `docutils/writers/html4css1/__init__.py` and 
`docutils/utils/__init__.py`, I would guess that this problem might come 
because docutils uses __file__ to find out where the source file is.


default_stylesheet_dirs = ['.', utils.relative_path(
os.path.join(os.getcwd(), 'dummy'), os.path.dirname(__file__))]

That trick doesn't work when the package is installed using pip. (I'm 
not absolutely sure about ahat I say, see `Accessing Data Files at Runtime

http://pythonhosted.org/distribute/setuptools.html#accessing-data-files-at-runtime`__
and
`Accessing Package Resources
http://peak.telecommunity.com/DevCenter/PythonEggs#accessing-package-resources`__)

Luc

--
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 http://groups.google.com/group/sphinx-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

[sphinx-users] Re: Cannot embed stylesheet messages

[Luc Saffre]

Oops again,

the new docutils version doesn't solve the problem, the message has just 
become more short:


partial node:: (ERROR/3) Cannot embed stylesheet 'html4css1.css': No 
such file or directory.


Otherwise it is still there, and it still doesn't cause any harm except 
disturbing the output of my build.


Luc

On 04/12/2013 12:08 PM, Luc Saffre wrote:

Oops, sorry, I somehow didn't read that thread until the end. The
solution for my problem is, as the thread reveals, to upgrade to the
development version of docutils instead of the released 0.10.

Lucky Luc
(who asks more quickly than his shadow)


On 04/12/2013 11:54 AM, Luc Saffre wrote:

Hi,

I use Sphinx 1.2b1 and docutils 0.10, both installed using pip in a
virtualenv, and I get a lot of error messages when I build my Sphinx
docs:

partial node:: (ERROR/3) Cannot embed stylesheet
'../../../pythonenvs/py27/local/lib/python2.7/site-packages/docutils/writers/html4css1/html4css1.css':

No such file or directory.

It looks as if the substring /local in the above filename is too much.
I do have a file named
`/home/luc/pythonenvs/py27/lib/python2.7/site-packages/docutils/writers/html4css1/html4css1.css`

(without the /local)

This error doesn't seem to stop the Sphinx build though, and all my
docs seem to render perfectly.

Martin Gignac (2013-03-12 15:38) reported a problem to docutils-users
which seems to be related:

[Docutils-users] Change in default location of html4css1.css in recent
snapshots?
http://sourceforge.net/mailarchive/forum.php?thread_name=CANf9dFNfFQD_hum%2BROYALaNGkvRDPn55UU_YS2gMKPri4o4jEA%40mail.gmail.comforum_name=docutils-users



He speaks about a --stylesheet-dirs option which he used as workaround.

Questions:

- Is there a way to specify this --stylesheet-dirs option from my
   Sphinx conf.py?
- Can somebody explain why this error doesn't cause any harm?
- How can I help to fix this problem?

Luc

(Besides this a big thankyou to all those who maintain Docutils and
Sphinx for their great work)




--
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 http://groups.google.com/group/sphinx-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

Re: [sphinx-users] [sphinx-dev] Sphinx 1.2 beta 1 released

[Luc Saffre]

I upgraded and rebuilt the following sites:

http://www.lino-framework.org/
http://welfare-user.lino-framework.org
http://welfare.lino-framework.org/
http://site.lino-framework.org/index.html
http://north.lino-framework.org/index.html

One little problem was because I had been using the fact that a hidden 
doctree was still visible in the sidebar. On 
http://www.lino-framework.org/ there is a heading Suggestions du chef 
which was a kind of manually written best of toctree. But the sidebar 
still was meant to show the official toctree. The new version forced me 
to remove the :hidden: and add a Sitemap section there. I think the 
new version is right, and I'll remove my Suggestions du chef section soon.


Thanks, Georg, for the good work!

Luc



On 31.03.2013 17:02, Georg Brandl wrote:

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

Hi all,

I'm very happy to announce the release of Sphinx 1.2, beta 1, available
on the Python package index at http://pypi.python.org/pypi/Sphinx.
Please test and report bugs to http://dev.sphinx-doc.org/sphinx/issues.

This is the first testing release for Sphinx 1.2, a new feature release
with lots of improvements and new features, such as better search results,
more support for internationalization and faster parallel builds.

For the full changelog, go to http://sphinx-doc.org/latest/changes.html.

What is it?
===

Sphinx is a tool that makes it easy to create intelligent and beautiful
documentation for Python projects (or other documents consisting of
multiple reStructuredText source files).

Website: http://sphinx-doc.org/

cheers,
Georg

-BEGIN PGP SIGNATURE-
Version: GnuPG v2.0.19 (GNU/Linux)

iEYEARECAAYFAlFYQekACgkQN9GcIYhpnLDuowCfe8WafoQw/Dd3ZK3HeRsQFIDc
qYYAn2OAc9DMEPxc5IhikDhAt7ma4akW
=Fmkk
-END PGP SIGNATURE-



--
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 http://groups.google.com/group/sphinx-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

Re: [sphinx-users] i18n language selection in sidebar

[Luc Saffre]

Yes, this is custom stuff (and wasn't yet checked in until some moments 
ago):


1) an addition to html_sidebars in the `conf.py 
https://code.google.com/p/lino-welfare/source/browse/userdocs/conf.py`_:


html_sidebars = {
   '**': ['select_lang.html', 'globaltoc.html', 'searchbox.html', 
'links.html'],

}

2) a file `select_lang.html 
https://code.google.com/p/lino-welfare/source/browse/userdocs/.templates/select_lang.html`_

in your templates directory.

This isn't really what i'd call elegant, but it's enough for me.

Luc

On 1.04.2013 10:35, Werner wrote:

Hi Luc,

I had a look at your sites you mentioned in beta 1.2 thread and noticed
the language selection in your left sidebar on:

http://welfare-user.lino-framework.org

Is this some custom stuff you did or is it a configuration option I
haven't noticed/found?

Werner



--
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 http://groups.google.com/group/sphinx-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

[sphinx-users] sphinx-apidoc and the `__init__.py` files

[Luc Saffre]

Hi all,

first of all, thanks for the `sphinx-apidoc` script, which is really 
very useful when developing and documenting large projects.


I noticed a subtle problem: it generates the wrong automodule directive 
for the `__init__.py` file of a package. I solved it for myself by 
adding a ``.replace('.__init__','')`` to line 73 of file `apidoc.py`:


before:

directive = '.. automodule:: %s\n' % makename(package, module)

after:

directive = '.. automodule:: %s\n' % \
  makename(package, module).replace('.__init__','')

I also wrote a blog entry about this problem:
http://lino-framework.org/blog/2013/0329.html#sphinx-apidoc-and-the-init-py-files

Luc

--
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 http://groups.google.com/group/sphinx-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.