From 4d3980404502defee1417dc12dad7e28cf28d1e7 Mon Sep 17 00:00:00 2001 From: Andrej730 Date: Fri, 21 Jun 2024 18:28:52 +0500 Subject: [PATCH] docs code block formatting `console` type code-block is designed mainly for examples of the console commands with the output. If it's just a shell script with comments, then `console` only gets in the way - e.g. if you try to select a console code block manually, you won't be able to select comment symbol `#` at the beginning of the command making code unrunnable if you try to copy and run it. I've replaced it with `bash` or `bat` (for Windows) code blocks where `console` wasn't necessary. I've also removed `$` symbols at the beginning of the commands if it's not a `console` code-block - since otherwise it just breaks "Copy Code Block" because you copy unrunnable code. --- .../docs/contribute/writing_docs.rst | 24 ++-- src/blenderbim/docs/devs/installation.rst | 92 ++++++------- src/blenderbim/docs/devs/running_tests.rst | 32 ++--- .../advanced/dealing_with_large_models.rst | 2 +- src/ifcopenshell-python/docs/ifccityjson.rst | 2 +- src/ifcopenshell-python/docs/ifcclash.rst | 16 +-- .../docs/ifcconvert/installation.rst | 4 +- .../docs/ifcconvert/usage.rst | 34 ++--- src/ifcopenshell-python/docs/ifccsv.rst | 2 +- src/ifcopenshell-python/docs/ifcdiff.rst | 6 +- .../docs/ifcopenshell-python/installation.rst | 12 +- .../docs/ifcopenshell/installation.rst | 126 +++++++++--------- src/ifcopenshell-python/docs/ifcpatch.rst | 18 +-- .../docs/ifcsverchok/installation.rst | 16 +-- .../docs/introduction/how_to_contribute.rst | 20 +-- 15 files changed, 203 insertions(+), 203 deletions(-) diff --git a/src/blenderbim/docs/contribute/writing_docs.rst b/src/blenderbim/docs/contribute/writing_docs.rst index a0147e5e03..ceaec10a9c 100644 --- a/src/blenderbim/docs/contribute/writing_docs.rst +++ b/src/blenderbim/docs/contribute/writing_docs.rst @@ -88,10 +88,10 @@ aware of should be bolded, titlecased, and used consistently. You *may* use italics to emphasize words or phrases. Inline code must be ``quoted`` and longer code snippets may use code blocks. -.. code-block:: console +.. code-block:: bash - $ cd /path/to/blenderbim - $ ls + cd /path/to/blenderbim + ls Be sure to specify the language to enable syntax highlighting. @@ -149,19 +149,19 @@ If you want to build the documentation locally, the documentation system uses `Sphinx `_. First, install the theme and theme dependencies: -.. code-block:: console +.. code-block:: bash - $ pip install furo - $ pip install sphinx-autoapi - $ pip install sphinx-copybutton + pip install furo + pip install sphinx-autoapi + pip install sphinx-copybutton Now you can generate the documentation: -.. code-block:: console +.. code-block:: bash - $ cd /path/to/ifcopenshell/src/blenderbim/docs/ - $ make html - $ cd _build/html - $ python -m http.server + cd /path/to/ifcopenshell/src/blenderbim/docs/ + make html + cd _build/html + python -m http.server You will now have a local webserver running hosting the documentation. diff --git a/src/blenderbim/docs/devs/installation.rst b/src/blenderbim/docs/devs/installation.rst index cfafe1bcbd..041dd2e836 100644 --- a/src/blenderbim/docs/devs/installation.rst +++ b/src/blenderbim/docs/devs/installation.rst @@ -47,11 +47,11 @@ compile IfcOpenShell is out of scope of this document. You can create your own package by using the Makefile as shown below. You can choose between a ``PLATFORM`` of ``linux``, ``macos``, ``macosm1``, and ``win``. You can choose between a ``PYVERSION`` of ``py311``, ``py310``, or ``py39``. -:: +.. code-block:: bash - $ cd src/blenderbim - $ make dist PLATFORM=linux PYVERSION=py311 - $ ls dist/ + cd src/blenderbim + make dist PLATFORM=linux PYVERSION=py311 + ls dist/ This will give you a fully packaged Blender add-on zip that you can distribute and install. @@ -75,68 +75,68 @@ restart Blender to see changes). For Linux or Mac: -.. code-block:: console +.. code-block:: bash - $ git clone https://github.com/IfcOpenShell/IfcOpenShell.git - $ cd IfcOpenShell + git clone https://github.com/IfcOpenShell/IfcOpenShell.git + cd IfcOpenShell # path to BlenderBIM addon # default path on Mac: "/Users/$USER/Library/Application Support/Blender/X.X/scripts/addons/blenderbim" # default path on Linux: "$HOME/.config/blender/X.X/" - $ BLENDER_ADDON_PATH="/path/to/blender/X.XX/scripts/addons/blenderbim" + BLENDER_ADDON_PATH="/path/to/blender/X.XX/scripts/addons/blenderbim" # Remove the Blender add-on Python code - $ rm -r $BLENDER_ADDON_PATH/core/ - $ rm -r $BLENDER_ADDON_PATH/tool/ - $ rm -r $BLENDER_ADDON_PATH/bim/ + rm -r $BLENDER_ADDON_PATH/core/ + rm -r $BLENDER_ADDON_PATH/tool/ + rm -r $BLENDER_ADDON_PATH/bim/ # Replace them with links to the Git repository - $ ln -s $PWD/src/blenderbim/blenderbim/core $BLENDER_ADDON_PATH/core - $ ln -s $PWD/src/blenderbim/blenderbim/tool $BLENDER_ADDON_PATH/tool - $ ln -s $PWD/src/blenderbim/blenderbim/bim $BLENDER_ADDON_PATH/bim + ln -s $PWD/src/blenderbim/blenderbim/core $BLENDER_ADDON_PATH/core + ln -s $PWD/src/blenderbim/blenderbim/tool $BLENDER_ADDON_PATH/tool + ln -s $PWD/src/blenderbim/blenderbim/bim $BLENDER_ADDON_PATH/bim # Copy over compiled IfcOpenShell files - $ cp $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell/*_wrapper* $PWD/src/ifcopenshell-python/ifcopenshell/ + cp $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell/*_wrapper* $PWD/src/ifcopenshell-python/ifcopenshell/ # Remove the IfcOpenShell dependency - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell + rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell # Replace them with links to the Git repository - $ ln -s $PWD/src/ifcopenshell-python/ifcopenshell $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell + ln -s $PWD/src/ifcopenshell-python/ifcopenshell $BLENDER_ADDON_PATH/libs/site/packages/ifcopenshell # Remove and link other IfcOpenShell utilities - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifccsv.py - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcdiff.py - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/bsdd.py - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/bcf - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifc4d - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifc5d - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifccityjson - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcclash - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcpatch - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifctester - $ rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcfm - $ rm -r $BLENDER_ADDON_PATH/libs/Desktop + rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifccsv.py + rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcdiff.py + rm -r $BLENDER_ADDON_PATH/libs/site/packages/bsdd.py + rm -r $BLENDER_ADDON_PATH/libs/site/packages/bcf + rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifc4d + rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifc5d + rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifccityjson + rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcclash + rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcpatch + rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifctester + rm -r $BLENDER_ADDON_PATH/libs/site/packages/ifcfm + rm -r $BLENDER_ADDON_PATH/libs/Desktop - $ ln -s $PWD/src/ifccsv/ifccsv.py $BLENDER_ADDON_PATH/libs/site/packages/ifccsv.py - $ ln -s $PWD/src/ifcdiff/ifcdiff.py $BLENDER_ADDON_PATH/libs/site/packages/ifcdiff.py - $ ln -s $PWD/src/bsdd/bsdd.py $BLENDER_ADDON_PATH/libs/site/packages/bsdd.py - $ ln -s $PWD/src/bcf/src/bcf $BLENDER_ADDON_PATH/libs/site/packages/bcf - $ ln -s $PWD/src/ifc4d/ifc4d $BLENDER_ADDON_PATH/libs/site/packages/ifc4d - $ ln -s $PWD/src/ifc5d/ifc5d $BLENDER_ADDON_PATH/libs/site/packages/ifc5d - $ ln -s $PWD/src/ifccityjson/ifccityjson $BLENDER_ADDON_PATH/libs/site/packages/ifccityjson - $ ln -s $PWD/src/ifcclash/ifcclash $BLENDER_ADDON_PATH/libs/site/packages/ifcclash - $ ln -s $PWD/src/ifcpatch/ifcpatch $BLENDER_ADDON_PATH/libs/site/packages/ifcpatch - $ ln -s $PWD/src/ifctester/ifctester $BLENDER_ADDON_PATH/libs/site/packages/ifctester - $ ln -s $PWD/src/ifcfm/ifcfm $BLENDER_ADDON_PATH/libs/site/packages/ifcfm - $ ln -s $PWD/src/blenderbim/blenderbim/libs/desktop $BLENDER_ADDON_PATH/libs/Desktop + ln -s $PWD/src/ifccsv/ifccsv.py $BLENDER_ADDON_PATH/libs/site/packages/ifccsv.py + ln -s $PWD/src/ifcdiff/ifcdiff.py $BLENDER_ADDON_PATH/libs/site/packages/ifcdiff.py + ln -s $PWD/src/bsdd/bsdd.py $BLENDER_ADDON_PATH/libs/site/packages/bsdd.py + ln -s $PWD/src/bcf/src/bcf $BLENDER_ADDON_PATH/libs/site/packages/bcf + ln -s $PWD/src/ifc4d/ifc4d $BLENDER_ADDON_PATH/libs/site/packages/ifc4d + ln -s $PWD/src/ifc5d/ifc5d $BLENDER_ADDON_PATH/libs/site/packages/ifc5d + ln -s $PWD/src/ifccityjson/ifccityjson $BLENDER_ADDON_PATH/libs/site/packages/ifccityjson + ln -s $PWD/src/ifcclash/ifcclash $BLENDER_ADDON_PATH/libs/site/packages/ifcclash + ln -s $PWD/src/ifcpatch/ifcpatch $BLENDER_ADDON_PATH/libs/site/packages/ifcpatch + ln -s $PWD/src/ifctester/ifctester $BLENDER_ADDON_PATH/libs/site/packages/ifctester + ln -s $PWD/src/ifcfm/ifcfm $BLENDER_ADDON_PATH/libs/site/packages/ifcfm + ln -s $PWD/src/blenderbim/blenderbim/libs/desktop $BLENDER_ADDON_PATH/libs/Desktop # Manually download some third party dependencies - $ cd $BLENDER_ADDON_PATH/bim/data/gantt - $ wget https://raw.githubusercontent.com/jsGanttImproved/jsgantt-improved/master/dist/jsgantt.js - $ wget https://raw.githubusercontent.com/jsGanttImproved/jsgantt-improved/master/dist/jsgantt.css - $ cd $BLENDER_ADDON_PATH/bim/schema - $ wget https://github.com/BrickSchema/Brick/releases/download/nightly/Brick.ttl + cd $BLENDER_ADDON_PATH/bim/data/gantt + wget https://raw.githubusercontent.com/jsGanttImproved/jsgantt-improved/master/dist/jsgantt.js + wget https://raw.githubusercontent.com/jsGanttImproved/jsgantt-improved/master/dist/jsgantt.css + cd $BLENDER_ADDON_PATH/bim/schema + wget https://github.com/BrickSchema/Brick/releases/download/nightly/Brick.ttl Or, if you're on Windows, you can use the batch script below. Before running it follow the instructions descibed after `rem` tags. diff --git a/src/blenderbim/docs/devs/running_tests.rst b/src/blenderbim/docs/devs/running_tests.rst index b8c50ec923..70ec544573 100644 --- a/src/blenderbim/docs/devs/running_tests.rst +++ b/src/blenderbim/docs/devs/running_tests.rst @@ -14,7 +14,7 @@ These tests use ``pytest`` as the test framework and runner, so install it: .. code-block:: bash - $ pip install pytest + pip install pytest All development is expected to use test driven development, and so we expect test coverage to be 100% where it is technically possible to test. @@ -42,10 +42,10 @@ similar. .. code-block:: bash - $ cd src/blenderbim/ - $ make test-core + cd src/blenderbim/ + make test-core # If you're on Windows, and don't want to use make, use: - $ pytest -p no:pytest-blender test/core + pytest -p no:pytest-blender test/core Tool tests ---------- @@ -59,9 +59,9 @@ following dependencies: .. code-block:: bash - $ pip install pytest-blender + pip install pytest-blender # Check that "Blender" is in your system's path - $ blender + blender On Windows, you can add Blender to the system path by doing: @@ -104,12 +104,12 @@ of all concrete functions. .. code-block:: bash - $ cd src/blenderbim/ - $ make test-tool # Test everything - $ make test-tool MODULE=foo # Only test a single module + cd src/blenderbim/ + make test-tool # Test everything + make test-tool MODULE=foo # Only test a single module # If you're on Windows, and don't want to use make, use: - $ pytest test/tool # Test everything - $ pytest test/tool/test_foo.py # Only test a single module + pytest test/tool # Test everything + pytest test/tool/test_foo.py # Only test a single module BlenderBIM Add-on tests ----------------------- @@ -128,9 +128,9 @@ test georeferencing features: ``Edit > Preferences > Add-ons`` and enable .. code-block:: bash - $ cd src/blenderbim/ - $ make test-bim # Test everything - $ make test-bim MODULE=foo # Only test a single module + cd src/blenderbim/ + make test-bim # Test everything + make test-bim MODULE=foo # Only test a single module # If you're on Windows, and don't want to use make, use: - $ pytest test/bim # Test everything - $ pytest test/bim -m "foo" ./ --maxfail=1 # Only test a single module + pytest test/bim # Test everything + pytest test/bim -m "foo" ./ --maxfail=1 # Only test a single module diff --git a/src/blenderbim/docs/users/advanced/dealing_with_large_models.rst b/src/blenderbim/docs/users/advanced/dealing_with_large_models.rst index b7f8556d94..1f47ddb800 100644 --- a/src/blenderbim/docs/users/advanced/dealing_with_large_models.rst +++ b/src/blenderbim/docs/users/advanced/dealing_with_large_models.rst @@ -185,7 +185,7 @@ You can automate model processing using this command (~5% speedup): .. code-block:: bash - $ blender -b -P headless_import.py + blender -b -P headless_import.py The ``headless_import.py`` script contains instructions on how to configure model loading settings. diff --git a/src/ifcopenshell-python/docs/ifccityjson.rst b/src/ifcopenshell-python/docs/ifccityjson.rst index a5b968aaf5..f542dce418 100644 --- a/src/ifcopenshell-python/docs/ifccityjson.rst +++ b/src/ifcopenshell-python/docs/ifccityjson.rst @@ -38,7 +38,7 @@ documentation: The example file that could be used is example/3D_BAG_example.json -.. code-block:: console +.. code-block:: bash python ifccityjson.py -i example/geometries.json -o output.ifc -n identificatie diff --git a/src/ifcopenshell-python/docs/ifcclash.rst b/src/ifcopenshell-python/docs/ifcclash.rst index 5448bdde91..5a6ee7c4d4 100644 --- a/src/ifcopenshell-python/docs/ifcclash.rst +++ b/src/ifcopenshell-python/docs/ifcclash.rst @@ -17,7 +17,7 @@ Source installation Here is a minimal example of how to use IfcPatch as a Python module or CLI utility: -:: +.. code-block:: console $ python -m ifcclash -h @@ -77,10 +77,10 @@ defined with data sources. Once your have your JSON description of your clashes, usage is like any other CLI app. -:: +.. code-block:: bash - $ ifcclash clash_sets.json - $ cat output.json + ifcclash clash_sets.json + cat output.json Here is a minimal example of how to use IfcClash as a library: @@ -106,13 +106,13 @@ Here is a minimal example of how to use IfcClash as a library: You can also alias it to a command: -:: +.. code-block:: bash - $ alias ifcclash='python -m ifcclash' + alias ifcclash='python -m ifcclash' Alternatively, you can package it as an executable. :: - $ python make.py - $ ./dist/ifcclash + python make.py + ./dist/ifcclash diff --git a/src/ifcopenshell-python/docs/ifcconvert/installation.rst b/src/ifcopenshell-python/docs/ifcconvert/installation.rst index 207d82eddf..f838174f97 100644 --- a/src/ifcopenshell-python/docs/ifcconvert/installation.rst +++ b/src/ifcopenshell-python/docs/ifcconvert/installation.rst @@ -43,9 +43,9 @@ Conda Docker ------ -.. code-block:: +.. code-block:: bash - $ docker run -it aecgeeks/ifcopenshell IfcConvert + docker run -it aecgeeks/ifcopenshell IfcConvert .. note:: diff --git a/src/ifcopenshell-python/docs/ifcconvert/usage.rst b/src/ifcopenshell-python/docs/ifcconvert/usage.rst index 1231ea5291..ef051216e0 100644 --- a/src/ifcopenshell-python/docs/ifcconvert/usage.rst +++ b/src/ifcopenshell-python/docs/ifcconvert/usage.rst @@ -7,9 +7,9 @@ Example commands For the most basic usage, specify an input and output file. The file extension you provide for the output file determines what format the IFC is converted to. -:: +.. code-block:: bash - $ IfcConvert /path/to/input.ifc /path/to/output.obj + IfcConvert /path/to/input.ifc /path/to/output.obj .. tip:: @@ -19,37 +19,37 @@ you provide for the output file determines what format the IFC is converted to. For any conversion, it is recommended to use multiple cores to speed up processing: -:: +.. code-block:: bash # Change "7" to the number of CPU cores you have then plus one. - $ IfcConvert -j 7 /path/to/input.ifc /path/to/output.dae + IfcConvert -j 7 /path/to/input.ifc /path/to/output.dae By default, units are converted to meters. If you want to retain the original units: -:: +.. code-block:: bash - $ IfcConvert --convert-back-units /path/to/input.ifc /path/to/output.stp + IfcConvert --convert-back-units /path/to/input.ifc /path/to/output.stp If your IFC uses large map coordinates and your desired format cannot handle it: -:: +.. code-block:: bash - $ IfcConvert --center-model /path/to/input.ifc /path/to/output.glb + IfcConvert --center-model /path/to/input.ifc /path/to/output.glb # Alternatively: - $ IfcConvert --center-model-geometry /path/to/input.ifc /path/to/output.glb + IfcConvert --center-model-geometry /path/to/input.ifc /path/to/output.glb # Or you can specify a manual offset in X;Y;Z format - $ IfcConvert --model-offset "10000;10000;0" /path/to/input.ifc /path/to/output.glb + IfcConvert --model-offset "10000;10000;0" /path/to/input.ifc /path/to/output.glb IfcConvert can be used to convert only specific elements. -:: +.. code-block:: bash # Convert only walls and slabs - $ IfcConvert --include entities IfcWall IfcSlab -v /path/to/input.ifc /path/to/output.glb + IfcConvert --include entities IfcWall IfcSlab -v /path/to/input.ifc /path/to/output.glb # Convert only these two particular elements filtered by GlobalId - $ IfcConvert --include attribute GlobalId 1yETHMphv6LwABqR4Pbs5g attribute GlobalId 1yETHMphv6LwABqR0Pbs5g -v /path/to/input.ifc /path/to/output.glb + IfcConvert --include attribute GlobalId 1yETHMphv6LwABqR4Pbs5g attribute GlobalId 1yETHMphv6LwABqR0Pbs5g -v /path/to/input.ifc /path/to/output.glb # Convert all objects on level 1. Note how "+" is used. - $ IfcConvert --include+=attribute Name "Level 1" -v /path/to/input.ifc /path/to/output.glb + IfcConvert --include+=attribute Name "Level 1" -v /path/to/input.ifc /path/to/output.glb .. warning:: @@ -58,15 +58,15 @@ IfcConvert can be used to convert only specific elements. IfcConvert can also be used to generate SVG floorplans: -:: +.. code-block:: bash - $ IfcConvert /path/to/input.ifc -yv /path/to/output.svg \ + IfcConvert /path/to/input.ifc -yv /path/to/output.svg \ -j 7 --exclude entities IfcOpeningElement IfcSpace CLI Manual ---------- -:: +.. code-block:: console $ IfcConvert -h diff --git a/src/ifcopenshell-python/docs/ifccsv.rst b/src/ifcopenshell-python/docs/ifccsv.rst index 34b114258c..5a53be8705 100644 --- a/src/ifcopenshell-python/docs/ifccsv.rst +++ b/src/ifcopenshell-python/docs/ifccsv.rst @@ -65,7 +65,7 @@ dependencies: Here is a minimal example of how to use IfcDiff as a Python module or CLI utility: -:: +.. code-block:: console $ python -m ifccsv -h usage: ifccsv.py [-h] -i IFC [-s SPREADSHEET] [-f FORMAT] [-d DELIMITER] [-n NULL] [-e EMPTY] [--bool_true BOOL_TRUE] [--bool_false BOOL_FALSE] [--concat CONCAT] [-q QUERY] [-a ATTRIBUTES [ATTRIBUTES ...]] diff --git a/src/ifcopenshell-python/docs/ifcdiff.rst b/src/ifcopenshell-python/docs/ifcdiff.rst index 1f82d4d400..3ea22f9b7e 100644 --- a/src/ifcopenshell-python/docs/ifcdiff.rst +++ b/src/ifcopenshell-python/docs/ifcdiff.rst @@ -34,7 +34,7 @@ Source installation Here is a minimal example of how to use IfcDiff as a Python module or CLI utility: -:: +.. code-block:: console $ python -m ifcdiff -h usage: ifcdiff.py [-h] [-o OUTPUT] [-r RELATIONSHIPS] old new @@ -72,9 +72,9 @@ Here is a minimal example of how to use IfcDiff as a library: You can also alias it to a command: -:: +.. code-block:: bash - $ alias ifcdiff='python -m ifcdiff' + alias ifcdiff='python -m ifcdiff' Using the BlenderBIM Add-on --------------------------- diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst b/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst index bf26e0eda7..d7012ce687 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst @@ -99,9 +99,9 @@ Conda Docker ------ -.. code-block:: +.. code-block:: bash - $ docker run -it aecgeeks/ifcopenshell python3 -c 'import ifcopenshell; print(ifcopenshell.version)' + docker run -it aecgeeks/ifcopenshell python3 -c 'import ifcopenshell; print(ifcopenshell.version)' .. note:: @@ -140,15 +140,15 @@ Gateways, etc. 5. Build the Docker image: - .. code-block:: + .. code-block:: bash - $ docker build -t lambda-ifcopenshell . + docker build -t lambda-ifcopenshell . 6. Run the Docker container: - .. code-block:: + .. code-block:: bash - $ docker run lambda-ifcopenshell + docker run lambda-ifcopenshell 7. Test lambda locally by following the `AWS guide on testing Lambda container images locally diff --git a/src/ifcopenshell-python/docs/ifcopenshell/installation.rst b/src/ifcopenshell-python/docs/ifcopenshell/installation.rst index 5faf3c6bf6..2e5cc9be8e 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell/installation.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell/installation.rst @@ -46,9 +46,9 @@ operating systems. GCC (4.7 or newer) or Clang (any version) is required. 1. Fetch the latest source code, including all submodules. - :: + .. code-block:: bash - $ git clone --recursive https://github.com/IfcOpenShell/IfcOpenshell.git + git clone --recursive https://github.com/IfcOpenShell/IfcOpenshell.git .. warning:: @@ -57,16 +57,16 @@ operating systems. GCC (4.7 or newer) or Clang (any version) is required. 2. Install basic dependencies: - :: + .. code-block:: bash - $ sudo apt-get install git cmake gcc g++ libboost-all-dev libcgal-dev + sudo apt-get install git cmake gcc g++ libboost-all-dev libcgal-dev 3. Install OpenCascade Technology (OCCT). Officially v7.5.0 is supported. Other versions may have unexpected behaviour. - :: + .. code-block:: bash - $ sudo apt-get install libocct-data-exchange-dev libocct-draw-dev libocct-foundation-dev libocct-modeling-algorithms-dev libocct-modeling-data-dev libocct-ocaf-dev libocct-visualization-dev + sudo apt-get install libocct-data-exchange-dev libocct-draw-dev libocct-foundation-dev libocct-modeling-algorithms-dev libocct-modeling-data-dev libocct-ocaf-dev libocct-visualization-dev .. seealso:: @@ -76,22 +76,22 @@ operating systems. GCC (4.7 or newer) or Clang (any version) is required. Another alternative is to use OpenCascade Community Edition (OCE), but it may lag behind OCCT and is no longer actively maintained so is not recommended. - :: + .. code-block:: bash - $ sudo apt-get install liboce-foundation-dev liboce-modeling-dev liboce-ocaf-dev liboce-visualization-dev liboce-ocaf-lite-dev + sudo apt-get install liboce-foundation-dev liboce-modeling-dev liboce-ocaf-dev liboce-visualization-dev liboce-ocaf-lite-dev As a final alternative, you may also manually compile OCE: - :: + .. code-block:: bash - $ sudo apt-get install libftgl-dev libtbb2 libtbb-dev libgl1-mesa-dev libfreetype6-dev - $ git clone https://github.com/tpaviot/oce.git - $ cd oce - $ mkdir build && cd build - $ cmake .. + sudo apt-get install libftgl-dev libtbb2 libtbb-dev libgl1-mesa-dev libfreetype6-dev + git clone https://github.com/tpaviot/oce.git + cd oce + mkdir build && cd build + cmake .. # Replace X with number of CPU cores + 1 - $ make -j X - $ sudo make install + make -j X + sudo make install .. warning:: @@ -102,40 +102,40 @@ operating systems. GCC (4.7 or newer) or Clang (any version) is required. 4. For building IfcConvert with COLLADA (.dae) support (ON by default), OpenCOLLADA is needed: - :: + .. code-block:: bash - $ sudo apt-get install libpcre3-dev libxml2-dev - $ git clone https://github.com/KhronosGroup/OpenCOLLADA.git - $ cd OpenCOLLADA + sudo apt-get install libpcre3-dev libxml2-dev + git clone https://github.com/KhronosGroup/OpenCOLLADA.git + cd OpenCOLLADA # Using a known good revision, but HEAD should work too: - $ git checkout 064a60b65c2c31b94f013820856bc84fb1937cc6 - $ mkdir build && cd build - $ cmake .. + git checkout 064a60b65c2c31b94f013820856bc84fb1937cc6 + mkdir build && cd build + cmake .. # Replace X with number of CPU cores + 1 - $ make -j X - $ sudo make install + make -j X + sudo make install 5. For building the IfcPython wrapper (ON by default), SWIG and Python development are needed: - :: + .. code-block:: bash - $ sudo apt-get install python-all-dev swig + sudo apt-get install python-all-dev swig 6. For building support for HDF5 caching (ON by default), install dependencies: - :: + .. code-block:: bash - $ sudo apt-get install libhdf5-dev libaec-dev zlibc + sudo apt-get install libhdf5-dev libaec-dev zlibc 7. Compile IfcOpenShell itself. - :: + .. code-block:: bash - $ cd /path/to/IfcOpenShell - $ mkdir build && cd build + cd /path/to/IfcOpenShell + mkdir build && cd build # Customise the compile options to suit your environment # Check all paths are valid for your environment - $ cmake ../cmake \ + cmake ../cmake \ -DOCC_LIBRARY_DIR=/usr/lib/x86_64-linux-gnu/ \ -DOCC_INCLUDE_DIR=/usr/include/ \ @@ -156,9 +156,9 @@ operating systems. GCC (4.7 or newer) or Clang (any version) is required. -DGMP_LIBRARY_DIR=/usr/lib/x86_64-linux-gnu \ -DMPFR_LIBRARY_DIR=/usr/lib/x86_64-linux-gnu # Replace X with number of CPU cores + 1 - $ make -j X + make -j X # Optionally install to the system - $ sudo make install + sudo make install Compiling on MacOS @@ -168,9 +168,9 @@ GCC (4.7 or newer) or Clang (any version) is required. 1. Fetch the latest source code, including all submodules. - :: + .. code-block:: bash - $ git clone --recursive https://github.com/IfcOpenShell/IfcOpenshell.git + git clone --recursive https://github.com/IfcOpenShell/IfcOpenshell.git .. warning:: @@ -179,22 +179,22 @@ GCC (4.7 or newer) or Clang (any version) is required. 2. Install all dependencies using `Homebrew `__ - :: + .. code-block:: bash - $ brew install boost cmake python3 cgal ftgl gmp libaec opencascade swig hdf5 zlib + brew install boost cmake python3 cgal ftgl gmp libaec opencascade swig hdf5 zlib # homebrew automatically links most libraries, except some keg-only ones - $ brew link zlib --force + brew link zlib --force 3. Build IfcOpenShell with flags for Homebrew dependencies: (``/usr/local/``) for Intel machines with x84_64 architecture, (``/opt/homebrew/``) for Apple Silicon processors with arm64 architecture. - :: + .. code-block:: bash - $ cd /path/to/IfcOpenShell - $ mkdir build && cd build + cd /path/to/IfcOpenShell + mkdir build && cd build # set library flags - $ export LDFLAGS="$LDFLAGS -Wl,-flat_namespace,-undefined,suppress" - $ cmake ../cmake \ + export LDFLAGS="$LDFLAGS -Wl,-flat_namespace,-undefined,suppress" + cmake ../cmake \ -DPYTHON_EXECUTABLE=/opt/homebrew/bin/python3.10 \ -DPYTHON_LIBRARY=/opt/homebrew/opt/python@3.10/Frameworks/Python.framework/Versions/3.10/lib/libpython3.10.dylib \ -DPYTHON_INCLUDE_DIR=/opt/homebrew/opt/python@3.10/Frameworks/Python.framework/Versions/3.10/include/python3.10/ \ @@ -207,7 +207,7 @@ GCC (4.7 or newer) or Clang (any version) is required. -DHDF5_INCLUDE_DIR=/opt/homebrew/include/ \ -DCOLLADA_SUPPORT=0 # `sysctl -n hw.ncpu` returns the number of cpu cores on macOS - $ make -j$(sysctl -n hw.ncpu) + make -j$(sysctl -n hw.ncpu) Compiling on Windows (Visual Studio) ------------------------------------ @@ -218,9 +218,9 @@ C++ Build Tools `__). 1. Fetch the latest source code, including all submodules. - :: + .. code-block:: bat - $ git clone --recursive https://github.com/IfcOpenShell/IfcOpenshell.git + git clone --recursive https://github.com/IfcOpenShell/IfcOpenshell.git .. warning:: @@ -230,17 +230,17 @@ C++ Build Tools `__). 2. Assuming Visual Studio 2015 x64 environment variables set, build dependencies and run cmake. - :: + .. code-block:: bat - $ cd IfcOpenShell\win - $ build-deps.cmd - $ run-cmake.bat + cd IfcOpenShell\win + build-deps.cmd + run-cmake.bat 3. Open and build the solution file in Visual Studio: - :: + .. code-block:: bat - $ ..\build-vs2015-x64\IfcOpenShell.sln + ..\build-vs2015-x64\IfcOpenShell.sln As the scripts default to using the ``RelWithDebInfo`` configuration, and a freshly created solution by CMake defaults to ``Debug``, make sure to switch the @@ -252,9 +252,9 @@ C++ Build Tools `__). project easily from the command-line (installing a project will build it also, if required): - :: + .. code-block:: bat - $ install-ifcopenshell.bat + install-ifcopenshell.bat .. seealso:: @@ -270,9 +270,9 @@ This is for users of `MSYS2 `__ and `MinGW 1. Fetch the latest source code, including all submodules. - :: + .. code-block:: bat - $ git clone --recursive https://github.com/IfcOpenShell/IfcOpenshell.git + git clone --recursive https://github.com/IfcOpenShell/IfcOpenshell.git .. warning:: @@ -281,12 +281,12 @@ This is for users of `MSYS2 `__ and `MinGW 2. Start the MSYS2 Shell and then: - :: + .. code-block:: bat - $ cd IfcOpenShell/win - $ ./build-deps.sh - $ ./run-cmake.sh - $ ./install-ifcopenshell.sh + cd IfcOpenShell/win + ./build-deps.sh + ./run-cmake.sh + ./install-ifcopenshell.sh .. seealso:: diff --git a/src/ifcopenshell-python/docs/ifcpatch.rst b/src/ifcopenshell-python/docs/ifcpatch.rst index 3ba68a6722..2c01303340 100644 --- a/src/ifcopenshell-python/docs/ifcpatch.rst +++ b/src/ifcopenshell-python/docs/ifcpatch.rst @@ -17,7 +17,7 @@ Source installation Here is a minimal example of how to use IfcPatch as a Python module or CLI utility: -:: +.. code-block:: console $ python -m ifcpatch -h @@ -45,10 +45,10 @@ This recipe expects one argument, which uses the :ref:`ifcopenshell-python/selector_syntax:filtering elements` syntax. In this example, we'll extract out all `IfcWall` elements. -:: +.. code-block:: bash - $ ifcpatch -i input.ifc -o output.ifc -r ExtractElements -a "IfcWall" - $ cat output.ifc + ifcpatch -i input.ifc -o output.ifc -r ExtractElements -a "IfcWall" + cat output.ifc Here is a minimal example of how to use IfcPatch as a library: @@ -66,16 +66,16 @@ Here is a minimal example of how to use IfcPatch as a library: You can also alias it to a command: -:: +.. code-block:: bash - $ alias ifcpatch='python -m ifcpatch' + alias ifcpatch='python -m ifcpatch' Alternatively, you can package it as an executable. -:: +.. code-block:: bash - $ python make.py - $ ./dist/ifcpatch + python make.py + ./dist/ifcpatch Patch recipes ------------- diff --git a/src/ifcopenshell-python/docs/ifcsverchok/installation.rst b/src/ifcopenshell-python/docs/ifcsverchok/installation.rst index b49ff5e600..4c40070bf3 100644 --- a/src/ifcopenshell-python/docs/ifcsverchok/installation.rst +++ b/src/ifcopenshell-python/docs/ifcsverchok/installation.rst @@ -71,23 +71,23 @@ Just symbolically link the IfcSverchok add-on files to your Git repository. If you're on Windows, use ``mklink`` instead. This allows us to code in our Git repository, and see the changes in our Blender installation. -:: +.. code-block:: bash - $ git clone https://github.com/IfcOpenShell/IfcOpenShell.git - $ cd IfcOpenShell + git clone https://github.com/IfcOpenShell/IfcOpenShell.git + cd IfcOpenShell # Link the repository to blender - $ ln -s src/ifcsverchok /path/to/blender/2.XX/scripts/addons/ifcsverchok + ln -s src/ifcsverchok /path/to/blender/2.XX/scripts/addons/ifcsverchok On Windows: -:: +.. code-block:: bat - $ git clone https://github.com/IfcOpenShell/IfcOpenShell.git - $ cd IfcOpenShell + git clone https://github.com/IfcOpenShell/IfcOpenShell.git + cd IfcOpenShell # Link the repository to blender - $ mklink /D "\path\to\blender\2.XX\scripts\addons\ifcsverchok" "\path\to\src\ifcsverchok" + mklink /D "\path\to\blender\2.XX\scripts\addons\ifcsverchok" "\path\to\src\ifcsverchok" After you modify your code in the Git repository, you will need to restart Blender for the changes to take effect. In ``Edit > Preferences > Add-ons`` you diff --git a/src/ifcopenshell-python/docs/introduction/how_to_contribute.rst b/src/ifcopenshell-python/docs/introduction/how_to_contribute.rst index 212eb0cba8..ee486a638d 100644 --- a/src/ifcopenshell-python/docs/introduction/how_to_contribute.rst +++ b/src/ifcopenshell-python/docs/introduction/how_to_contribute.rst @@ -24,21 +24,21 @@ If you want to build the documentation locally, the documentation system uses `Sphinx `_. First, install Sphinx and dependencies: -.. code-block:: console +.. code-block:: bash - $ pip install sphinx - $ pip install sphinx-autoapi - $ pip install sphinx-copybutton - $ pip install furo + pip install sphinx + pip install sphinx-autoapi + pip install sphinx-copybutton + pip install furo Now you can generate the documentation: -.. code-block:: console +.. code-block:: bash - $ cd /path/to/ifcopenshell/src/ifcopenshell-python/docs/ - $ make html - $ cd _build/html - $ python -m http.server + cd /path/to/ifcopenshell/src/ifcopenshell-python/docs/ + make html + cd _build/html + python -m http.server You will now have a local webserver running hosting the documentation.