Обсуждение: HTML/PDF Build Errors

Hi Sarah,

On Fri, Dec 21, 2018 at 3:16 AM Sarah Conway Schnurr
<xenophenes42@gmail.com> wrote:
>
> Hello!
>
> Came across a couple of errors when building HTML and PDF files with the Makefile.
>
> System Info
>
> CentOS 7
> pdfTeX 3.1415926-2.5-1.40.14 (TeX Live 2013)
> pgadmin4-3.2
>
> HTML
>
> (Relevant) Output:
>
> $ make docs
> ...
> `tablespace_dialog.rst:: WARNING: document isn't included in any toctree`

There's something very odd going on there - I can see from the git
history that tablespace_dialog has been in the toc tree since at least
mid 2016
(https://git.postgresql.org/gitweb/?p=pgadmin4.git;a=history;f=docs/en_US/managing_cluster_objects.rst;h=a0d520ec187811f0c2bb3b28d8f196011730caee;hb=f62d35bf3c92a643c7d7f07b89df7ddff56bbf93)

Is it present in your copy of managing_cluster_objects.rst?

How did you get your source code BTW? Please test with 3.6 or git head
- 3.2 is obsolete now.

> Adding it to ignore_patterns in conf.py results in:
>
> Exception occurred:
>   File "/usr/lib/python2.7/site-packages/sphinx/builders/html.py", line 407, in get_doc_context
>     display_toc = (self.env.toc_num_entries[docname] > 1),
> KeyError: 'tablespace_dialog'
>
> Deleting the file in question - tablespace_dialog.rst - (obviously not the ideal solution) resolves the error and
allowsthe files to be built as expected.
 
>
> PDF
>
> (Relevant) Output
>
> $ make docs-pdf
> ...
> (/usr/share/texlive/texmf-dist/tex/latex/psnfss/t1phv.fd) [1{/usr/share/texlive
> /texmf/fonts/map/pdftex/updmap/pdftex.map}] [2]
> Adding blank page after the table of contents.
> pdfTeX warning (ext4): destination with the same identifier (name{page.i}) has
> been already used, duplicate ignored
> <to be read again>
>                    \relax
> l.113 \tableofcontents
>                        [1]pdfTeX warning (ext4): destination with the same iden
> tifier (name{page.ii}) has been already used, duplicate ignored
> <to be read again>
>                    \relax
> l.113 \tableofcontents
>                        [2] <logo-right-128.png, id=23, 128.48pt x 128.48pt>
> <use logo-right-128.png> <use logo-right-128.png> [1 <./logo-right-128.png>]
> [2]
> Chapter 1.
> ! Use of \@icentercr doesn't match its definition.
> <argument> \def
>
> l.128 ...r{\index{Getting Started}Getting Started}
>
> ?
>
> Have not found a workaround for the PDF issue as of yet.
>
> Are these actual bugs or am I missing some kind of dependency?
>
> Thanks very much for your time & help, ahead of time.
>
> --
> Sarah Conway Schnurr



-- 
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Hi

On Fri, Dec 21, 2018 at 2:49 PM Sarah Conway Schnurr
<xenophenes42@gmail.com> wrote:
>
> Looks like the tablespace_dialog.rst was a processing/environmental error on my end. Please disregard.
>
> However, there's another error I forgot to mention previously that is reproducible in the community packages from Git
forboth 3.2, 3.6, and HEAD, on a clean install:
 
>
> Running Sphinx v1.1.3
> loading pickled environment... not yet created
>
> Theme error:
> no theme named 'classic' found (missing theme.conf?)
> make[1]: *** [html] Error 1
> make[1]: Leaving directory `/home/sarah/websites/pgadmin4/docs/en_US'
> make: *** [docs] Error 2
>
> Removing that line fixes the error, but as before, not ideal:

Is your Sphinx an RPM installation? If so, they may have split that
theme out into a different package. We always install using PIP, which
works fine in every case I know of.

> sed -i "/html_theme = 'classic'/d" docs/en_US/conf.py
>
> The PDF errors as mentioned previously in detail are additionally reproducible in the community packages from Git for
3.2,3.6, and HEAD.
 
>
> ! Use of \@icentercr doesn't match its definition.

Yeah, I see that as well. There's something in the doc source that is
getting converted into invalid TEX I think. I have no idea what
though, as I haven't really used TEX directly in 20+ years. It seems
like a Sphinx bug, in that it's quite happy with the input for other
formats, but barfs on anything that uses TEX.

Do you know anyone that is familiar with TEX that might be able to
help? Maybe Joe?

> On Fri, Dec 21, 2018 at 1:59 AM Dave Page <dpage@pgadmin.org> wrote:
>>
>> Hi Sarah,
>>
>> On Fri, Dec 21, 2018 at 3:16 AM Sarah Conway Schnurr
>> <xenophenes42@gmail.com> wrote:
>> >
>> > Hello!
>> >
>> > Came across a couple of errors when building HTML and PDF files with the Makefile.
>> >
>> > System Info
>> >
>> > CentOS 7
>> > pdfTeX 3.1415926-2.5-1.40.14 (TeX Live 2013)
>> > pgadmin4-3.2
>> >
>> > HTML
>> >
>> > (Relevant) Output:
>> >
>> > $ make docs
>> > ...
>> > `tablespace_dialog.rst:: WARNING: document isn't included in any toctree`
>>
>> There's something very odd going on there - I can see from the git
>> history that tablespace_dialog has been in the toc tree since at least
>> mid 2016
(https://git.postgresql.org/gitweb/?p=pgadmin4.git;a=history;f=docs/en_US/managing_cluster_objects.rst;h=a0d520ec187811f0c2bb3b28d8f196011730caee;hb=f62d35bf3c92a643c7d7f07b89df7ddff56bbf93)
>>
>> Is it present in your copy of managing_cluster_objects.rst?
>>
>> How did you get your source code BTW? Please test with 3.6 or git head
>> - 3.2 is obsolete now.
>>
>> > Adding it to ignore_patterns in conf.py results in:
>> >
>> > Exception occurred:
>> >   File "/usr/lib/python2.7/site-packages/sphinx/builders/html.py", line 407, in get_doc_context
>> >     display_toc = (self.env.toc_num_entries[docname] > 1),
>> > KeyError: 'tablespace_dialog'
>> >
>> > Deleting the file in question - tablespace_dialog.rst - (obviously not the ideal solution) resolves the error and
allowsthe files to be built as expected.
 
>> >
>> > PDF
>> >
>> > (Relevant) Output
>> >
>> > $ make docs-pdf
>> > ...
>> > (/usr/share/texlive/texmf-dist/tex/latex/psnfss/t1phv.fd) [1{/usr/share/texlive
>> > /texmf/fonts/map/pdftex/updmap/pdftex.map}] [2]
>> > Adding blank page after the table of contents.
>> > pdfTeX warning (ext4): destination with the same identifier (name{page.i}) has
>> > been already used, duplicate ignored
>> > <to be read again>
>> >                    \relax
>> > l.113 \tableofcontents
>> >                        [1]pdfTeX warning (ext4): destination with the same iden
>> > tifier (name{page.ii}) has been already used, duplicate ignored
>> > <to be read again>
>> >                    \relax
>> > l.113 \tableofcontents
>> >                        [2] <logo-right-128.png, id=23, 128.48pt x 128.48pt>
>> > <use logo-right-128.png> <use logo-right-128.png> [1 <./logo-right-128.png>]
>> > [2]
>> > Chapter 1.
>> > ! Use of \@icentercr doesn't match its definition.
>> > <argument> \def
>> >
>> > l.128 ...r{\index{Getting Started}Getting Started}
>> >
>> > ?
>> >
>> > Have not found a workaround for the PDF issue as of yet.
>> >
>> > Are these actual bugs or am I missing some kind of dependency?
>> >
>> > Thanks very much for your time & help, ahead of time.
>> >
>> > --
>> > Sarah Conway Schnurr
>>
>>
>>
>> --
>> Dave Page
>> Blog: http://pgsnake.blogspot.com
>> Twitter: @pgsnake
>>
>> EnterpriseDB UK: http://www.enterprisedb.com
>> The Enterprise PostgreSQL Company
>
>
>
> --
> Sarah Conway Schnurr



-- 
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Hi

On Fri, Dec 21, 2018 at 3:04 PM Sarah Conway Schnurr
<xenophenes42@gmail.com> wrote:
>
>
>>
>> Is your Sphinx an RPM installation? If so, they may have split that
>> theme out into a different package. We always install using PIP, which
>> works fine in every case I know of.
>
>
> No, it's installed through pip as well. Might it be version specific? I'm on the latest version supported by pip,
Sphinxv1.1.3.
 

Hmm, odd. Well if it helps any, all our CI/CD systems (Windows, Mac,
Linux, Docker) all rebuild the virtual environment on every test run
and build, based on just a plain old 'pip install sphinx' (as well as
the other requirements in requirements.txt).

>> > sed -i "/html_theme = 'classic'/d" docs/en_US/conf.py
>> >
>> > The PDF errors as mentioned previously in detail are additionally reproducible in the community packages from Git
for3.2, 3.6, and HEAD.
 
>> >
>> > ! Use of \@icentercr doesn't match its definition.
>>
>> Yeah, I see that as well. There's something in the doc source that is
>> getting converted into invalid TEX I think. I have no idea what
>> though, as I haven't really used TEX directly in 20+ years. It seems
>> like a Sphinx bug, in that it's quite happy with the input for other
>> formats, but barfs on anything that uses TEX.
>>
>> Do you know anyone that is familiar with TEX that might be able to
>> help? Maybe Joe?
>
>
> I'll do some research and see if I can determine what syntax it might be unhappy about; if able to figure it out,
willfollow up here with the fix.
 

Awesome - thanks!

-- 
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Hi

On Sat, Dec 29, 2018 at 3:57 AM Sarah Conway Schnurr
<xenophenes42@gmail.com> wrote:
>
> Sorry about the delay, didn't actually revisit the issue until today.
>
> When you run sphinx-build (sphinx-build -b latex $SRC $DST), it generates the chapter titles like so:
>
> \chapter{\index{Getting Started}Getting Started}
>
> whereas they need to be:
>
> \chapter{Getting Started}
>
> Cleaning that up manually or running the following sed command fixes it and seems to generate a perfectly fine PDF:
>
> sed -Ei 's/chapter\{\\index\{(.*?)\}(.*?)}/chapter{\1}/g' ${DST}/pgadmin4.tex
>
> There may be a way to prevent sphinx-build from creating this error in the first place, but wanted to share my
workaroundin case someone else comes across this error. Hopefully that helps!
 

Awesome - thanks! I wonder if that's because they are marked in the
RST like this:

***************************************
`Add named restore point Dialog`:index:
***************************************

Would removing the :index: fix the issue?


> On Fri, Dec 21, 2018 at 7:17 AM Dave Page <dpage@pgadmin.org> wrote:
>>
>> Hi
>>
>> On Fri, Dec 21, 2018 at 3:04 PM Sarah Conway Schnurr
>> <xenophenes42@gmail.com> wrote:
>> >
>> >
>> >>
>> >> Is your Sphinx an RPM installation? If so, they may have split that
>> >> theme out into a different package. We always install using PIP, which
>> >> works fine in every case I know of.
>> >
>> >
>> > No, it's installed through pip as well. Might it be version specific? I'm on the latest version supported by pip,
Sphinxv1.1.3.
 
>>
>> Hmm, odd. Well if it helps any, all our CI/CD systems (Windows, Mac,
>> Linux, Docker) all rebuild the virtual environment on every test run
>> and build, based on just a plain old 'pip install sphinx' (as well as
>> the other requirements in requirements.txt).
>>
>> >> > sed -i "/html_theme = 'classic'/d" docs/en_US/conf.py
>> >> >
>> >> > The PDF errors as mentioned previously in detail are additionally reproducible in the community packages from
Gitfor 3.2, 3.6, and HEAD.
 
>> >> >
>> >> > ! Use of \@icentercr doesn't match its definition.
>> >>
>> >> Yeah, I see that as well. There's something in the doc source that is
>> >> getting converted into invalid TEX I think. I have no idea what
>> >> though, as I haven't really used TEX directly in 20+ years. It seems
>> >> like a Sphinx bug, in that it's quite happy with the input for other
>> >> formats, but barfs on anything that uses TEX.
>> >>
>> >> Do you know anyone that is familiar with TEX that might be able to
>> >> help? Maybe Joe?
>> >
>> >
>> > I'll do some research and see if I can determine what syntax it might be unhappy about; if able to figure it out,
willfollow up here with the fix.
 
>>
>> Awesome - thanks!
>>
>> --
>> Dave Page
>> Blog: http://pgsnake.blogspot.com
>> Twitter: @pgsnake
>>
>> EnterpriseDB UK: http://www.enterprisedb.com
>> The Enterprise PostgreSQL Company
>
>
>
> --
> Sarah Conway Schnurr



-- 
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise PostgreSQL Company