Major documentation refactoring (#4905)

2026-09-27 02:31:09 +00:00 · 2024-06-21 10:54:05 +03:00
parent 1e26587bd3
commit f921b65953
80 changed files with 1775 additions and 121 deletions
@@ -1,49 +1,196 @@
-Let's get started
-=================
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  BlenderBIM Reference Manual
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

-The BlenderBIM Add-on lets you analyse, create, and modify OpenBIM with Blender.
+Welcome to the manual for `BlenderBIM <https://blenderbim.org>`__,
+the free and open source BIM add-on for Blender.

-**Quickstart video tutorial**
+Quickstart
+==========

-Learn how to model a small building and create simple architectural plans, sections, 2D details, and sheet layouts in this short tutorial series.
+.. only:: builder_html and (not singlehtml)

-`View all tutorial videos <https://www.youtube.com/playlist?list=PLMDcOjMJYxUPHHvEHqAsOuBdSPsp6or32>`__
+   .. container:: toc-cards

-.. raw:: html
+      .. container:: card

-    <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/videoseries?list=PLMDcOjMJYxUPHHvEHqAsOuBdSPsp6or32" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+         :doc:`/users/quickstart/introduction_to_bim` (2-minute read)
+            Brief overview of BIM concepts and BlenderBIM's role.

-.. note::
+      .. container:: card

-   This documentation is incomplete. Would you like to help write more? `Get in touch! <https://osarch.org/chat/>`__
+         :doc:`/users/quickstart/installation` (5 to 10-minute process)
+            Installation guide and system requirements.
+
+      .. container:: card
+
+         :doc:`/users/quickstart/explore_model` (15-minute guide)
+            Load and navigate an IFC model.
+
+      .. container:: card
+
+         :doc:`/users/quickstart/create_model` (20-minute guide)
+            Create a simple BIM project.
+
+.. container:: global-index-toc
+
+   .. toctree::
+      :hidden:
+      :caption: Quickstart
+      :maxdepth: 1
+
+      users/quickstart/introduction_to_bim
+      users/quickstart/installation
+      users/quickstart/explore_model
+      users/quickstart/create_model
+      users/quickstart/next_steps
+
+Sections
+========
+
+.. only:: builder_html and (not singlehtml)
+
+   .. container:: toc-cards
+
+      .. container:: card
+
+         :doc:`/users/modeling/interface`
+            Guide to the BlenderBIM interface.
+
+      .. container:: card
+
+         :doc:`/users/modeling/ifc_modeling`
+            IFC modeling techniques and concepts.
+
+      .. container:: card
+
+         :doc:`/users/drawing/index`
+            2D drawing generation and annotation.
+
+      .. container:: card
+
+         :doc:`/users/advanced/index`
+            Advanced topics and large-scale modeling.
+
+      .. container:: card
+
+         :doc:`/users/tutorials/index`
+            Real-world BIM project tutorials.
+
+      .. container:: card
+
+         :doc:`/users/user_interface`
+            Detailed UI reference.
+
+      .. container:: card
+
+         :doc:`/users/appendix/index`
+            Troubleshooting and additional resources.
+
+.. container:: global-index-toc
+
+   .. toctree::
+      :hidden:
+      :caption: Sections
+      :maxdepth: 2
+
+      users/modeling/interface
+      users/modeling/ifc_modeling
+      users/drawing/index
+      users/advanced/index
+      users/tutorials/index
+      users/user_interface
+      users/appendix/index
+
+Get Involved
+============
+
+This manual is maintained largely by volunteers.
+
+Please consider joining the effort and :doc:`/contribute/writing_docs`.
+
+You can also can help with :doc:`Translations and Internationalisation </contribute/translations>`
+
+For users who want to contribute to the BlenderBIM codebase,
+please refer to the :doc:`Documentation for Developers </devs/getting_started>`.
+This part of the documentation covers various aspects of the BlenderBIM development process.
+
+You can get in touch by `joining the chat <https://osarch.org/chat/>`__.

 .. toctree::
   :hidden:
+   :caption: Get Involved
   :maxdepth: 1
-   :caption: For users:

-   users/introduction_to_bim
-   users/installation
-   users/exploring_an_ifc_model
-   users/creating_an_ifc_model
-   users/georeferencing
-   users/dealing_with_large_models
-   users/git_support
-   users/other_addons
-   users/user_interface
-   users/troubleshooting
+   contribute/writing_docs
+   contribute/translations

-.. toctree::
-   :hidden:
-   :maxdepth: 1
-   :caption: For developers:

-   devs/installation
-   devs/hello_world
-   devs/code_style
-   devs/running_tests
-   devs/writing_docs
-   devs/translations
-   devs/undo_system
-   devs/system_support
-   devs/ux_guidelines
+Developer Documentation
+=======================
+
+BlenderBIM is an open-source project, and its development is driven by the contributions of a dedicated community of developers,
+architects, engineers, and enthusiasts. If you're interested in contributing to the project, whether by submitting bug reports,
+suggesting new features, or contributing code, your involvement is highly encouraged and appreciated.
+
+
+
+.. only:: builder_html and (not singlehtml)
+
+   .. container:: toc-cards
+
+      .. container:: card
+
+         :doc:`/devs/getting_started`
+            Introduction to contributing to BlenderBIM.
+
+      .. container:: card
+
+         :doc:`/devs/installation`
+            Setting up a development environment.
+
+      .. container:: card
+
+         :doc:`/devs/hello_world`
+            Understanding the project structure.
+
+      .. container:: card
+
+         :doc:`/devs/undo_system`
+            Working with BlenderBIM's undo system.
+
+      .. container:: card
+
+         :doc:`/devs/code_style`
+            Code style guidelines and best practices.
+
+      .. container:: card
+
+         :doc:`/devs/running_tests`
+            Testing and quality assurance.
+
+      .. container:: card
+
+         :doc:`/devs/system_support`
+            Multiplatform compatibility.
+
+      .. container:: card
+
+         :doc:`/devs/ux_guidelines`
+            User experience and interface guidelines.
+
+.. container:: global-index-toc
+
+   .. toctree::
+      :hidden:
+      :caption: Developer Documentation
+      :maxdepth: 1
+
+      devs/getting_started
+      devs/installation
+      devs/hello_world
+      devs/undo_system
+      devs/code_style
+      devs/running_tests
+      devs/system_support
+      devs/ux_guidelines