Skip to content

Conversation

@digu-007
Copy link
Contributor

This PR fixes issue #666.

I have added all the files as stated in the issue, with proper outputs and comments.

Kindly, please review.

@mloskot
Copy link
Member

mloskot commented Feb 10, 2020

@digu-007 I suggest you to have a look at the ongoing review of another example in PR #665 and auto-review your PR addressing the comments posted by @vissarion to the #665, if applicable of coruse.
Chances are you will clear some of potential issues.

@barendgehrels
Copy link
Collaborator

Looks promising - but they are not called yet. They need to be referred to from source code.
See indeed also the comments of #665 and please look in one of the existing examples to see how they are referred to

@digu-007
Copy link
Contributor Author

Looks promising - but they are not called yet. They need to be referred to from source code.
See indeed also the comments of #665 and please look in one of the existing examples to see how they are referred to

Referred to from source code means that you need me to add exact header files of the algorithms?
I will work on the doxygen commands as well.

@vissarion
Copy link
Member

Referred to from source code means that you need me to add exact header files of the algorithms?
I will work on the doxygen commands as well.

No need to add extra header files, just inject doxygen code in them.

See for example densify algorithm:
https://github.com/boostorg/geometry/blob/develop/include/boost/geometry/algorithms/densify.hpp#L401

And you have to inject doxygen code in you example as well.
See:
https://github.com/boostorg/geometry/blob/develop/doc/src/examples/algorithms/densify.cpp#L11

@vissarion
Copy link
Member

Adding images for the geometries in your example will give an extra value on the documentation and help the reader even more.

@digu-007
Copy link
Contributor Author

Adding images for the geometries in your example will give an extra value on the documentation and help the reader even more.

Ok sure, working on it.

@digu-007
Copy link
Contributor Author

Adding images for the geometries in your example will give an extra value on the documentation and help the reader even more.

Can you please tell me the importance of /*<-*/ create_svg("union.svg", green, blue, output); /*->*/?
I have made the png file for the required image, and is writing [$img/algorithms/covered_by.png] at the bottom of output enough?

@vissarion
Copy link
Member

vissarion commented Feb 11, 2020

Adding images for the geometries in your example will give an extra value on the documentation and help the reader even more.

Can you please tell me the importance of /*<-*/ create_svg("union.svg", green, blue, output); /*->*/?
I have made the png file for the required image, and is writing [$img/algorithms/covered_by.png] at the bottom of output enough?

this is code (commented out to not appear in the example) to create the svg file for the example and is used for future reference. AFAIU, the png displayed in the documentation is generated by manually converting the generated svg to png in some application (e.g. inkscape).

So creating the png, adding something like [$img/algorithms/covered_by.png] and storing the png to html/img/algorithms/ should be fine.

It is recomened to generate the documentation on your side and test everything is OK.

@digu-007
Copy link
Contributor Author

Adding images for the geometries in your example will give an extra value on the documentation and help the reader even more.

Can you please tell me the importance of /*<-*/ create_svg("union.svg", green, blue, output); /*->*/?
I have made the png file for the required image, and is writing [$img/algorithms/covered_by.png] at the bottom of output enough?

this is code (commented out to not appear in the example) to create the svg file for the example and is used for future reference. AFAIU, the png displayed in the documentation is generated by manually converting the generated svg to png in some application (e.g. inkscape).

So creating the png, adding something like [$img/algorithms/covered_by.png] and storing the png to html/img/algorithms/ should be fine.

It is recomened to generate the documentation on your side and test everything is OK.

I added images and example files to imports.qbk here. Can you please review it.

I'm getting bugs while generating the documentation, can you help me with that?

@mloskot
Copy link
Member

mloskot commented Feb 11, 2020

@digu-007

I'm getting bugs while generating the documentation, can you help me with that?

You need to be (very) specific:

Mind you, crystal spheres are not always handy with their guessing magic.

@digu-007
Copy link
Contributor Author

I'm getting bugs while generating the documentation, can you help me with that?

You need to be (very) specific:

  • how do you build the docs exactly
  • what commands you run exactly
  • what errors you get exactly

Mind you, crystal spheres are not always handy with their guessing magic.

I followed Generating-and-Improving-Documentation, and while executing make_qbk.py, I got the following error.
error

@mloskot
Copy link
Member

mloskot commented Feb 11, 2020

That Wiki page say:

Compile doxygen_xml2qbk tool shipped with Boost.Geometry....

which I presume you have not attempted.
That is why you are getting the doxygen_xml2qbk not found error.

I also think you probably should use the current develop branch, not the Boost 1.72 archive, especially, that you are submitting PRs which can only be submitted against the develop branch.

@digu-007
Copy link
Contributor Author

That Wiki page say:

Compile doxygen_xml2qbk tool shipped with Boost.Geometry....

which I presume you have not attempted.
That is why you are getting the doxygen_xml2qbk not found error.

I also think you probably should use the current develop branch, not the Boost 1.72 archive, especially, that you are submitting PRs which can only be submitted against the develop branch.

I am using develop branch only for PRs and not the Boost 1.72, it's just that I was building the documentation using Boost 1.72 just to check how to build, but now I won't use it.

Yes I forgot about doxygen_xml2qbk.

I installed Doxygen and QuickBook with the help of this but while running b2, I'm getting following error:
this

Also can you please verify latest commit. I made the necessary changes to imports.qbk and added images for better understanding of examples.

@mloskot
Copy link
Member

mloskot commented Feb 11, 2020

I was building the documentation using Boost 1.72 just to check how to build

You can build documentation from git repo. I'd simply work in the cloned Boost superproject as it is the common way any Boost library is developed.

I'm getting following error ...

I suspect you just cloned the boostorg/geometry repository.

You need to clone the whole Boost super-project as it is explained in

Also can you please verify latest commit.

First, let's get your documentation build to working state.

@digu-007
Copy link
Contributor Author

You need to clone the whole Boost super-project as it is explained in

I cloned the whole Boost super-project, switched to develop branch and ran .\bootstrap.sh. But .\b2 headers is giving error zsh: command not found: .b2

@mloskot
Copy link
Member

mloskot commented Feb 11, 2020

@digu-007 What shell/console/command line are you familiar with, Windows, Unix or both? Are you familiar with the difference between .\program vs ./program conventions?

I suspect you are using Linux. I'd say, it should be quite plain obvious for you to run ./b2.

The Wiki pages try to do its best, present git and b2 commands a reader needs to run, but they do not cover all conventions for all command lines. So, a reader needs to apply environments-specific adjustments, obviously.

@digu-007
Copy link
Contributor Author

The Wiki pages try to do its best, present git and b2 commands a reader needs to run, but they

I did ./b2 headers and got output ...found 1171 targets.... I did export PATH=$PATH:$HOME/boost to add Boost directory to PATH but b2 test is not working.

/home/digu_j/boost/tools/build/src/tools/features/warnings-feature.jam:27: in load
ERROR: rule "[[bbv2.builtin.features.warnings]]`warnings`::" unknown in module "warnings-feature".
/home/digu_j/boost/tools/build/src/kernel/modules.jam:295: in import
/home/digu_j/boost/tools/build/src/tools/features/__init_features__.jam:22: in load
/home/digu_j/boost/tools/build/src/kernel/modules.jam:295: in import
/home/digu_j/boost/tools/build/src/tools/builtin.jam:16: in load
/home/digu_j/boost/tools/build/src/kernel/modules.jam:295: in import
/home/digu_j/boost/tools/build/src/build-system.jam:12: in load
/home/digu_j/boost/tools/build/src/kernel/modules.jam:295: in import
/home/digu_j/boost/tools/build/src/kernel/bootstrap.jam:139: in boost-build
/home/digu_j/boost/boost-build.jam:17: in module scope

@mloskot
Copy link
Member

mloskot commented Feb 11, 2020

I did ./b2 headers and got output ...found 1171 targets...

Good, that seems like you've got all headers deployed/symlinked in boost/ sub-directory of the cloned Boost repository.

I did export PATH=$PATH:$HOME/boost to add Boost directory to PATH

That is not strictly necessary. You can just run b2 specifying absolute or relative path.

Try to replicate the commands I run below:

$ pwd
/mnt/d/boost.wsl

$ ls
CMakeLists.txt  Jamroot          README.md     b2     boost-build.jam  boost.png     bootstrap.bat  bootstrap.sh  doc        index.html  more                rst.css  tools
INSTALL         LICENSE_1_0.txt  appveyor.yml  boost  boost.css        boostcpp.jam  bootstrap.log  dist          index.htm  libs        project-config.jam  status

$ ./b2 headers
Performing configuration checks

    - default address-model    : 64-bit (cached)
    - default architecture     : x86 (cached)
    - symlinks supported       : yes (cached)
...found 1171 targets...

$ ls ./boost
accumulators             concept                      filesystem.hpp

$ cd libs/geometry/

$ ../../b2 test
Performing configuration checks

    - default address-model    : 64-bit
    - default architecture     : x86
    - symlinks supported       : yes
...patience...
...patience...
...patience...
...patience...
...found 11821 targets...
...updating 2757 targets...
...on 100th target...
...on 200th target...
gcc.compile.c++ ../../bin.v2/libs/geometry/test/util/util_math_abs.test/gcc-9/debug/threading-multi/visibility-hidden/math_abs.o
gcc.compile.c++ ../../bin.v2/libs/geometry/test/util/util_math_sqrt.test/gcc-9/debug/threading-multi/visibility-hidden/math_sqrt.o
gcc.compile.c++ ../../bin.v2/libs/geometry/test/util/util_calculation_type.test/gcc-9/debug/threading-multi/visibility-hidden/calculation_type.o
gcc.link ../../bin.v2/libs/geometry/test/util/util_math_abs.test/gcc-9/debug/threading-multi/visibility-hidden/util_math_abs
testing.capture-output ../../bin.v2/libs/geometry/test/util/util_math_abs.test/gcc-9/debug/threading-multi/visibility-hidden/util_math_abs.run
**passed** ../../bin.v2/libs/geometry/test/util/util_math_abs.test/gcc-9/debug/threading-multi/visibility-hidden/util_math_abs.test
...

UPDATE: I asked about the problem on the lists and it's likely a problem with using old b2 installed from Linux packages instead of b2 built in the current Boost superproject tree, see https://lists.boost.org/Archives/boost/2020/03/248336.php

@digu-007
Copy link
Contributor Author

digu-007 commented Feb 11, 2020

$ ../../b2 test

These tests are running for more than two hours in my system, is there any way to up speed the process?

@mloskot
Copy link
Member

mloskot commented Feb 11, 2020

Buy more cores, e.g. 16 or more ;)

It's thousands of programs to compile and link. However, just kill it. You don't have to run all those tests for your purpose of docs. You run that command and let a bunch of tests build as verification you have basic setup ready and b2 command works, and you kill it.

@digu-007
Copy link
Contributor Author

Buy more cores, e.g. 16 or more ;)

Maybe ;)

Yes, b2 works and I guess the setup is ready. I will run the qbk files tomorrow to generate the changes that I made and check for any errors.

@digu-007
Copy link
Contributor Author

digu-007 commented Feb 12, 2020

Where could I load the html page of an algorithm from, after editing/adding files and running python make_qbk.py?
/boost/libs/geometry/doc/html is showing only img index.html svg_simplify_country.png svg_simplify_road.png

Output of make_qbk.py

Boost.Geometry is making .qbk files in /home/digu_j/boost/libs/geometry/doc
Boost.Geometry is cleaning Doxygen files in /home/digu_j/boost/libs/geometry/doc/doxy/doxygen_output/xml/
performance:-1: warning: multiple use of section label 'performance', (first occurrence: /home/digu_j/boost/libs/geometry/doc/doxy/doxygen_input/pages/doxygen_pages.hpp, line 152)
Warning: template parameter Point has no type in franklin
Warning: template parameter PointOfSegment has no type in franklin
Warning: template parameter Point has no type in crossings_multiply
Warning: template parameter PointOfSegment has no type in crossings_multiply
Parameter not found: width_height
Boost.Geometry is cleaning Doxygen files in /home/digu_j/boost/libs/geometry/doc/index/xml/
/home/digu_j/boost/boost/geometry/index/equal_to.hpp:165: warning: The following parameters of boost::geometry::index::detail::equal_to::operator()(Value const &l, Value const &r, Strategy const &strategy) const are not documented:
  parameter 'strategy'
/home/digu_j/boost/boost/geometry/index/equal_to.hpp:225: warning: The following parameters of boost::geometry::index::detail::equal_to< boost::tuple< T0, T1, T2, T3, T4, T5, T6, T7, T8, T9 >, false >::operator()(value_type const &l, value_type const &r, Strategy const &strategy) const are not documented:
  parameter 'strategy'
/home/digu_j/boost/boost/geometry/index/equal_to.hpp:194: warning: The following parameters of boost::geometry::index::detail::equal_to< std::pair< T1, T2 >, false >::operator()(std::pair< T1, T2 > const &l, std::pair< T1, T2 > const &r, Strategy const &strategy) const are not documented:
  parameter 'strategy'
/home/digu_j/boost/boost/geometry/index/equal_to.hpp:288: warning: The following parameters of boost::geometry::index::detail::equal_to< std::tuple< Args... >, false >::operator()(value_type const &l, value_type const &r, Strategy const &strategy) const are not documented:
  parameter 'strategy'
/home/digu_j/boost/boost/geometry/index/equal_to.hpp:165: warning: The following parameters of boost::geometry::index::detail::equal_to::operator()(Value const &l, Value const &r, Strategy const &strategy) const are not documented:
  parameter 'strategy'
/home/digu_j/boost/boost/geometry/index/equal_to.hpp:225: warning: The following parameters of boost::geometry::index::detail::equal_to< boost::tuple< T0, T1, T2, T3, T4, T5, T6, T7, T8, T9 >, false >::operator()(value_type const &l, value_type const &r, Strategy const &strategy) const are not documented:
  parameter 'strategy'
/home/digu_j/boost/boost/geometry/index/equal_to.hpp:194: warning: The following parameters of boost::geometry::index::detail::equal_to< std::pair< T1, T2 >, false >::operator()(std::pair< T1, T2 > const &l, std::pair< T1, T2 > const &r, Strategy const &strategy) const are not documented:
  parameter 'strategy'
/home/digu_j/boost/boost/geometry/index/equal_to.hpp:288: warning: The following parameters of boost::geometry::index::detail::equal_to< std::tuple< Args... >, false >::operator()(value_type const &l, value_type const &r, Strategy const &strategy) const are not documented:
  parameter 'strategy'
Performing configuration checks

    - default address-model    : 64-bit (cached)
    - default architecture     : x86 (cached)
    - symlinks supported       : yes (cached)
...patience...
...patience...
...patience...
...found 5093 targets...
...updating 1 target...
quickbook.quickbook-to-boostbook ../../../bin.v2/libs/geometry/doc/gcc-7/debug/python-3.7/threading-multi/visibility-hidden/geometry.boostbook
Generating output file: ../../../bin.v2/libs/geometry/doc/gcc-7/debug/python-3.7/threading-multi/visibility-hidden/geometry.boostbook
...updated 1 target...

@mloskot
Copy link
Member

mloskot commented Feb 12, 2020

@digu-007

Once you have that configuration in place, you will see 4 targets built:

$ cd libs/geometry/doc
$ python3 make_qbk.py
...
Performing configuration checks

    - default address-model    : 64-bit (cached)
    - default architecture     : x86 (cached)
    - symlinks supported       : yes (cached)
...patience...
...patience...
...patience...
...found 5085 targets...
...updating 4 targets...
quickbook.quickbook-to-boostbook ../../../bin.v2/libs/geometry/doc/gcc-9/debug/python-2.7/threading-multi/visibility-hidden/geometry.xml
Generating output file: ../../../bin.v2/libs/geometry/doc/gcc-9/debug/python-2.7/threading-multi/visibility-hidden/geometry.xml
xslt-xsltproc ../../../bin.v2/libs/geometry/doc/gcc-9/debug/python-2.7/threading-multi/visibility-hidden/geometry.docbook
xslt-xsltproc-dir html/geometry_HTML.manifest
...updated 4 targets...

Finally, load libs/geometry/doc/html/index.html and you will have all generated content linked from libs/geometry/doc/html/geometry/*, clickable and accessible.

@digu-007
Copy link
Contributor Author

@mloskot Can you tell me how to add boostbook to user-config.jam. While running make_qbk.py only 3 targets are getting updated, I think boostbook is causing that bug. Although HTML files are built now and I can check all my work!

@mloskot
Copy link
Member

mloskot commented Feb 12, 2020

@digu-007

Can you tell me how to add boostbook to user-config.jam

Well, have you tried to follow http://www.boost.org/doc/libs/release/doc/html/quickbook/install.html ?

In #667 (comment) you said you followed Generating-and-Improving-Documentation. I assume you followed the "Preparation" section too. Am I missing anything?

While running make_qbk.py only 3 targets are getting updated

Yes, because your setup is missing the user-config.jam.

@digu-007
Copy link
Contributor Author

@mloskot Yes, I did setup user-config.jam according to this.

Here have a look:

using xsltproc ;

using boostbook
    : /usr/share/xml/docbook/stylesheet/nwalsh
    : /usr/share/xml/docbook/schema/dtd/4.2
    ;

# Remove this line if you're not using doxygen
using doxygen ;

using quickbook
    : /usr/local/bin/quickbook
    ;

@mloskot
Copy link
Member

mloskot commented Feb 12, 2020

Then your question "Can you tell me how to add boostbook to user-config.jam" in #667 (comment) is confusing.

Anyway, here is mine

$ sudo apt-get install xsltproc docbook-xsl docbook-xml libxslt1.1
$ cat ~/user-config.jam
using xsltproc ;

using boostbook
    : /usr/share/xml/docbook/stylesheet/nwalsh
    : /usr/share/xml/docbook/schema/dtd/4.2
    ;

using doxygen ;

If you are still not getting the HTML generated, try to clean the stuff:

$ cd libs/geometry/doc/
$ python3 make_qbk.py --release-build   # this will clean, w/o running b2
$ python3 make_qbk.py                   # this will double-clean and run b2

You may see ...updated 3 targets... or ...updated 4 targets... depending what b2 finds out of date (e.g. bin.v2 folder in Boost root directory has been removed).

However, important is if you see this lines at the end of the python make_qbk.py output, that is building of the HTML:

xslt-xsltproc ../../../bin.v2/libs/geometry/doc/gcc-9/debug/python-2.7/threading-multi/visibility-hidden/geometry.docbook
xslt-xsltproc-dir html/geometry_HTML.manifest

@digu-007
Copy link
Contributor Author

Anyway, here is mine

$ sudo apt-get install xsltproc docbook-xsl docbook-xml libxslt1.1

Oh this is the command for boostbook, sorry then, I have indeed installed that.

You may see ...updated 3 targets...

Yes I'm getting that, and HTML are generated fine.

quickbook.quickbook-to-boostbook ../../../bin.v2/libs/geometry/doc/gcc-7/debug/python-3.7/threading-multi/visibility-hidden/geometry.xml
Generating output file: ../../../bin.v2/libs/geometry/doc/gcc-7/debug/python-3.7/threading-multi/visibility-hidden/geometry.xml
xslt-xsltproc ../../../bin.v2/libs/geometry/doc/gcc-7/debug/python-3.7/threading-multi/visibility-hidden/geometry.docbook
xslt-xsltproc-dir html/geometry_HTML.manifest
...updated 3 targets...

So I guess, everything is fine and I will work on final integration of the example codes and respective images to the frontend.

@mloskot
Copy link
Member

mloskot commented Feb 12, 2020

$ sudo apt-get install xsltproc docbook-xsl docbook-xml libxslt1.1

Oh this is the command for boostbook, sorry then, I have indeed installed that.

That apt-get installs DocBook XML/XSL files required by BoostBook, as BoostBook documentation format is an extension of DocBook.

This is complex system indeed.

@digu-007
Copy link
Contributor Author

digu-007 commented Feb 12, 2020

I finally linked all the examples and images to the frontend. I verified all the results by locally testing.
@mloskot Kindly, please check this

@awulkiew
Copy link
Member

awulkiew commented Feb 12, 2020

Btw, AFAIR instead of running make_qbk.py manually you can run b2 doc/. This way the b2 will install everything build the prerequisites for you.

@mloskot
Copy link
Member

mloskot commented Feb 12, 2020

This way the b2 will install everything for you.

I think it's a bit too optimistic 😄

The b2 will build doxygen_xml2qbk and run the make_qbk.py workflow.
It will not install everything though, i.e.

geometry/doc/readme.txt

Lines 16 to 17 in 5226efc

1) install Doxygen
2) install QuickBook using http://www.boost.org/doc/libs/release/doc/html/quickbook/install.html

@digu-007 digu-007 requested a review from vissarion February 12, 2020 18:51
@awulkiew
Copy link
Member

@mloskot yes, I should've written "build the prerequisites". ;)

@digu-007 digu-007 requested review from awulkiew and mloskot February 12, 2020 19:24
Copy link
Member

@vissarion vissarion left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am ok for merging (after addressing my minor comment)! Thanks @digu-007

Edit: I didn't build/check the docs on my side, but the code looks ok to me.

// Boost.Geometry (aka GGL, Generic Geometry Library)
// QuickBook Example

// Copyright (c) 2020-2021 Digvijay Janartha, Hamirpur, India.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we usually only include the running year, so 2020 is enough

Copy link
Member

@mloskot mloskot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well done. Extra credits for patience! :)

@digu-007
Copy link
Contributor Author

@vissarion I fixed years in all the files.
Kindly review it.

@awulkiew
Copy link
Member

Thanks for the PR!

@vissarion vissarion merged commit 60405ce into boostorg:develop Feb 13, 2020
@digu-007
Copy link
Contributor Author

@mloskot @vissarion @awulkiew @barendgehrels
Thanks for assisting and building the documentation! :)

@digu-007 digu-007 deleted the issue666 branch February 13, 2020 19:32
mloskot added a commit that referenced this pull request Mar 2, 2020
Correct example comment (copy/paste error).

Fixes issue introduced in #667
@mloskot
Copy link
Member

mloskot commented Mar 2, 2020

FYI, in 53a6ada I committed quick fix for this issue that sneaked in

Generating output file: /root/build/boost/bin.v2/libs/geometry/doc/gcc-5.4.0/debug/python-2.7/threading-multi/visibility-hidden/geometry.xml
/root/project/libs/geometry/doc/src/examples/algorithms/touches_two_geometries.cpp:11: error: Template Redefinition: touches
/root/project/libs/geometry/doc/src/examples/algorithms/touches_two_geometries.cpp:49: error: Template Redefinition: touches_output

It broke global Boost docs build, so I had to react quick.

@digu-007
Copy link
Contributor Author

digu-007 commented Mar 2, 2020

FYI, in 53a6ada I committed quick fix for this issue that sneaked in

@mloskot Thank you for solving the bug! I remember that bug occurred during testing, I don't know how I lost track of it before the final commit.

@vissarion vissarion added this to the 1.73 milestone Mar 16, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants