For the online docs it doesn't make too much sense to use global sequences for figures and tables. However, for a PDF export of the whole document it would be good to have it. Find a way to make this possible with ReadTheDocs.

The pandoc conversion of the original docx document produced only one rst file. The whole split up into files has been done by me on behalf what I thought makes sense. Not too long documents and subfolders where there were many subsections.

There are some general changes that need to be discussed, though. The current structure is as follows:

1. intro folder: Online docs should have a first steps chapter that jumps straight at using the software. First, I thought, I have to write something up, but then I found that chapter 3 from the documentation serves this purpose quite well. I have also included the Docker chapter in the intro folder.
2. 3dcitydb folder: This one contains chapter 1, 2 and 4 from the docx version.
3. impexp folder: Contains 5 and 6.
4. wfs folder: unchanged
5. webmap folder: unchanged (split up the big features chapter to multiple files)
6. appendix stuff is part of the main source directory

Sometimes, I changed some headings as they where quite long in the original document (like "Running and using the Importer/Exporter" --> "Interfaces"). I kept the names of the rst files very short. I used names twice and more, but within the folders it should make sense, I think.

Anyway, feel free to give feedback.

According to the README.md there should be a make file for Linux, but I can only find the make.bat for Windows. Or is the Makefile meant to be used?

XML code decoration works with .. code-block:: xml. We should make use of it especially in the XML query chapters of the CityGML Export and in the WFS docs.

The docx conversion with pandoc created just one big rst files with all the image links at the bottom. As the docs are now split up to multiple files, the same has to be done for the image references. They are now living in the img-links.rst file.

Maybe someone wants to write a small Python script that puts the image references in the correct files :)

I've created a webhook in the ReadTheDocs admin backend, but it seems this is not enough to trigger a build when the GitHub repo changes. It needs to be setup in GitHub is well: https://docs.readthedocs.io/en/stable/webhooks.html#github

The webhook URL is: readthedocs.org/api/v2/webhook/3dcitydb-docs/80391/

In the original documents we used formatting for table, function of file names quite heavily at times. Unfortunately, this was not reflected during the conversion of the docx document. It would be nice to also format such names in the online documentation with two ` signs. This is going to be a longer task and it's fine if we not provide it immediatly ;)

We also have to see, how it looks in the final result. Because of the grey background it can also get too distracting to read probably. So we have to agree what to format and what not.

Check where SQL code can use some syntac highlighting with .. code-block:: sql

With the new web docs we have the possibility to create

.. note:
Note blocks

and

.. warning
Warning blocks

The note blocks were all created manually after the pandoc conversion. I've added some warning blocks as well. But we should check, if there can be more warnings or if some note blocks are too big and should better be part of the normal text.

Firstly, this is a hugely rich source of information! Fantastic!

Secondly, my team and I are running into a steep learning-curve barrier and were wondering if there were recipes for marshalling data into the cityDB schemas for completely new cities from existing data (OSM, etc...). All existing tutorials either point me to 1) download existing GML data (does not edify on how to create new data) from cities that have been in development for 10+ years like Munich, Singapore, or Berlin, or 2) input data by hand. There doesn't seem to be guidance for setting up a completely new city in a semi-automated way to get city-wide baseline data.

I'm trying to get my research team to adopt cityDB but they are pushing back with the fact that, although there are hand-wavy guides (e.g. "just look at the schema and figure it out") there does not seem to be any step by step instructions for this which is a red-flag for adoption.

Any guidance would be greatly appreciated if possible!

ReadTheDocs seems like a nice portal to publish the 3DCityDB docs. After registering you can simply import a GitHub repo and then it's published.

The final link would then be: https://3dcitydb.readthedocs.io/en/latest/
I think, that's a nice URL name :)

Reflect the newer name "VIS Export" used in the current version of the Importer/Exporter as mentioned in

3dcitydb/importer-exporter#266

I locally installed the Sphinx copybutton extension using pip install sphinx-copybutton.

However, when running the Gradle build task, it fails with the following error messages:

15:39:50.999 [QUIET] [system.out] Running Sphinx v3.4.3
15:39:51.146 [QUIET] [system.out] Original exception:
15:39:51.147 [QUIET] [system.out] Traceback (most recent call last):
15:39:51.147 [QUIET] [system.out]   File "sphinx\registry.py", line 417, in load_extension
15:39:51.147 [QUIET] [system.out]   File "importlib\__init__.py", line 127, in import_module
15:39:51.147 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
15:39:51.147 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 983, in _find_and_load
15:39:51.147 [QUIET] [system.out]
15:39:51.147 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 965, in _find_and_load_unlocked
15:39:51.147 [QUIET] [system.out] ModuleNotFoundError: No module named 'sphinx_copybutton'
15:39:51.147 [QUIET] [system.out]
15:39:51.147 [QUIET] [system.out] Traceback (most recent call last):
15:39:51.148 [QUIET] [system.out]   File "sphinx\registry.py", line 417, in load_extension
15:39:51.148 [QUIET] [system.out]   File "importlib\__init__.py", line 127, in import_module
15:39:51.148 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
15:39:51.148 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 983, in _find_and_load
15:39:51.148 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 965, in _find_and_load_unlocked
15:39:51.148 [QUIET] [system.out] ModuleNotFoundError: No module named 'sphinx_copybutton'
15:39:51.148 [QUIET] [system.out]
15:39:51.148 [QUIET] [system.out] The above exception was the direct cause of the following exception:
15:39:51.148 [QUIET] [system.out]
15:39:51.148 [QUIET] [system.out] Traceback (most recent call last):
15:39:51.148 [QUIET] [system.out]   File "sphinx\cmd\build.py", line 279, in build_main
15:39:51.148 [QUIET] [system.out]   File "sphinx\application.py", line 245, in __init__
15:39:51.148 [QUIET] [system.out]   File "sphinx\application.py", line 402, in setup_extension
15:39:51.148 [QUIET] [system.out]   File "sphinx\registry.py", line 421, in load_extension
15:39:51.148 [QUIET] [system.out] sphinx.errors.ExtensionError: Could not import extension sphinx_copybutton (exception: No module named 'sphinx_copybutton')

The docx conversion produced many different heading styles starting.
chapter: =====
subchapter: -----
subsubchapter: ~~~~~
section: ^^^^^
subsection: ''''

I left most of them unchanged (except for subsection), but have seen that it's also common to use === at the top of each file. Not sure, how it then turns out if somebody wants to creates one PDF document out of it. Hopefully the structure of folders and index.rst files takes care of correct alignment and numbering. Here is how Sphinx handles headings.

The current documentation includes many cross chapter references. In an online documentation they are not so helpful and should at least include links to corresponding file + section.

We should still use the name of the "chapter", though, in case somebody exports all the docs to a PDF. Not sure, if we just drop the chapter number (don't know how Sphinx does numbering).

The online docs, latest, refers to version 4.2 of 3DCityDB but the latest release is 4.1.
...or is the docs for future releases published already? Sorry for being stupid

There are two small problems:

1. Tables spanning multiple pages are not properly displayed (see: p.89 and p90)
2. The size of table cell is not automatically adjusted according to the text length. (see p.10)

A PDF version of the 3dcitydb-docs can be downloaded from here:
https://3dcitydb-docs.readthedocs.io/_/downloads/en/release-v4.2.3/pdf/

@Son-HNguyen would you like to look into this issue?

It seems that we used word markers for lots of GUI images which were not part of the image files itself. Unfortunately, these got not converted and are now missing :(

The list of links from the original document can now be embedded in the text. Maybe somebody wants to write a small script that takes the hyperlinks from the links.rst file and inserts them in the correct positions of the text.

Same as with SQL and XML, all bash command should be formatted, too:

.. code:: bash

Issue

Currently, the docs advise to use the deprecated --link to create a bridged network.

Solution

Document the use of custom networks, e.g:

docker network create citydb
docker run -d --name citydb --nework citydb -e ...