Building the docs - error

Q&A
1

I’m trying to build the gmt documentation, but ran into the following problem:

$ cmake --build . --target docs_html 
[  0%] Copying doc/rst/source ...
[  0%] Built target _docs_copy_rst_tree_source
[  0%] Built target _docs_rst_mkdir_verbatim
[  0%] Built target script2verbatim
[ 15%] Built target _docs_examples_verbatim
[ 15%] Copying doc/rst/_extensions ...
[ 15%] Built target _docs_copy_rst_tree__extensions
[ 15%] Copying doc/rst/themes ...
[ 15%] Built target _docs_copy_rst_tree_themes
[ 15%] Copying doc/rst/_templates ...
[ 15%] Built target _docs_copy_rst_tree__templates
[ 15%] Built target _docs_rst_src
[ 15%] Copying doc/rst/_static ...
[ 15%] Built target _docs_copy_rst_tree__static
[ 15%] Built target _docs_rst_mkdir_images
[ 20%] Built target _docs_copy_fig
[ 20%] Built target gen_gmt_headers
[ 21%] Built target pslib
[ 54%] Built target gmtlib
[ 54%] Built target gmt
[ 54%] Built target gmt_for_img_convert
gmake[3]: *** No rule to make target 'doc/scripts/images/GMT_RGBchart.ps', needed by 'doc/rst/source/_images/images/GMT_RGBchart.pdf'.  Stop.
gmake[2]: *** [CMakeFiles/Makefile2:1351: doc/scripts/CMakeFiles/_docs_html_scripts_fig.dir/all] Error 2
gmake[1]: *** [CMakeFiles/Makefile2:1303: doc/rst/CMakeFiles/docs_html.dir/rule] Error 2
gmake: *** [Makefile:569: docs_html] Error 2

This didn’t happen some weeks/months ago. Anything changed? I see that dvc is needed to pull in the images(?). Based on https://docs.generic-mapping-tools.org/dev/devdocs/contributing.html#building-the-documentation

2

Yes, for master you will need to install dvc and follow those instructions.

3

Did a dvc pull, but still god the error. Must investigate more.

4

I suggest wipe the build dir and cmake from scratch.

5

Sounds like a good idea.

6

Wiping the build dir did the trick. However:

  • sphinx-panels seems to be a dependency, but not mentioned (maybe others as well?). Also, how to install sphinx et al should be mentioned, it is isnt already.

  • optimize_images removed?

    $ cmake --build . --target optimize_images
gmake: *** No rule to make target 'optimize_images'.  Stop.

  • [100%] Built target docs_depends
[100%] Building manpages...
/home/anbj/gmt/b/doc/rst/source/animations.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/changes.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/cookbook.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/datasets.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/deprecated-defaults.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/api.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/contributing.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/debug.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/devdocs.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/maintenance.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/postscriptlight.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/rst-cheatsheet.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/team.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/gallery.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/migrating.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/modules.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/modules-classic.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/std-opts-classic.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/switching.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/tutorial.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/tutorial_jl.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/users-contrib-scripts.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/users-contrib-symbols.rst: WARNING: document isn't included in any toctree

    Maybe adding :orphan: should fix this? If it needs to be fixed.

  • dvc pull should be done inside the build directory; given that it resides within the cloed gmt source tree (see docs). I use a build directory that is outside the cloned gmt source directory, so dvc pull does not work. Maybe improve wording on this.

7
  • sphinx-panels seems to be a dependency, but not mentioned (maybe others as well?). Also, how to install sphinx et al should be mentioned, it is isnt already.

sphinx-panels and other sphinx extensions are already included in the GMT repository (see https://github.com/GenericMappingTools/gmt/tree/master/doc/rst/_extensions), so that people who build the documentation don’t need to install these extensions. Of course, sphinx should be installed and the related instructions are available at Home · GenericMappingTools/gmt Wiki · GitHub.

  • optimize_images removed?
$ cmake --build . --target optimize_images
gmake: *** No rule to make target 'optimize_images'.  Stop.

optimize_images needs pngquant. The target is unavailable if pngquant is not installed on your system.

[100%] Built target docs_depends
[100%] Building manpages...
/home/anbj/gmt/b/doc/rst/source/animations.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/changes.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/cookbook.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/datasets.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/deprecated-defaults.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/api.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/contributing.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/debug.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/devdocs.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/maintenance.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/postscriptlight.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/rst-cheatsheet.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/devdocs/team.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/gallery.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/migrating.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/modules.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/modules-classic.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/std-opts-classic.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/switching.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/tutorial.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/tutorial_jl.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/users-contrib-scripts.rst: WARNING: document isn't included in any toctree
/home/anbj/gmt/b/doc/rst/source/users-contrib-symbols.rst: WARNING: document isn't included in any toctree

Maybe adding :orphan: should fix this? If it needs to be fixed.

Yes, it’s a known problem but I don’t have a solution yet. If adding :orphan: works, please submit a PR.

  • dvc pull should be done inside the build directory; given that it resides within the cloed gmt source tree (see docs). I use a build directory that is outside the cloned gmt source directory, so dvc pull does not work. Maybe improve wording on this.

Actually, dvc pull can be done in any directories inside the GMT source tree.

8

Thanks seisman. Will look into.

About dvc pull; my build directory is not inside the GMT source tree, so I get an error. Maybe this is OK.

9

Thanks for trying this. I just posted a somewhat-related discussion topic on GitHub.

1 Like
10

Sorry for reviving this old thread, but I’m having the same problem.

ninja: error: '/home/anbj/.gmt/gmt/doc/scripts/images/GMT_RGBchart.ps', needed by 'doc/rst/source/_images/GMT_RGBchart.pdf', missing and no known rule to make it

Doing a dvc pull gives me this:

[... snip ...]
doc/scripts/images/GMT_base_symbols3.ps
doc/scripts/images/GMT_tut_11.ps
doc/examples/images/ex02.ps
Is your cache up to date?
<https://error.dvc.org/missing-files>

Has anyone built the docs recently with success?

I’ve tried on several computers, wiped the build directory, etc., but it does not help.

11

It must be due to a problem with dvc. The CI tests are currently all failing withe the same message

Is your cache up to date?
12

Should I create an issue for this? Who deals with the dvc stuff?

13

Dongdong know this stuff. Don’t know if related but almost coincidental with the start of this problem I received a message from Github warning about a change in the MS cache policy (saying something like "to have more than ?? MB you have to start pay).

14

Argh, can’t stand that. Lure them in, and then start charging money.

I created an issue for this (Problems building docs: dvc pull error · Issue #8807 · GenericMappingTools/gmt · GitHub).

I don’t remember the discussions and I didn’t take part in it (I think), but do we have to use dvc? Can’t we generate (huge) PS’es locally during building?

I don’t like having to sync with anything else than github..

15

Yes, you need the PS files that are currently stored in DVC. They aren’t huge, just many.

16

Can’t the PS files be generated by gmt on the system, locally?

17

Well, you do when you run the tests, but need something (the truth) to compare with. And that is the DVC stored files.

18

Alright. Thanks @Joaquim. Let’s see if Dongdong knows how to fix it.

19

Dongdong to the rescue. See Problems building docs: dvc pull error · Issue #8807 · GenericMappingTools/gmt · GitHub.