diff --git a/.gitignore b/.gitignore index 85501469..bfe93d0a 100644 --- a/.gitignore +++ b/.gitignore @@ -15,4 +15,5 @@ SetupWriteRead5.3mf v093reout.3mf .vs .idea -cmake-build-* \ No newline at end of file +cmake-build-* +venv diff --git a/.readthedocs.yml b/.readthedocs.yml index 0054d1cf..a1595951 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,26 +1,21 @@ -# .readthedocs.yml -# Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +# .readthedocs.yml - Configuration for MkDocs on Read the Docs -# Required version: 2 - build: os: ubuntu-22.04 tools: - python: "3.7" + python: "3.9" # Python 3.9+ recommended for better compatibility -# Build documentation in the docs/ directory with Sphinx -sphinx: - configuration: Documentation/conf.py +# Use MkDocs instead of Sphinx +mkdocs: + configuration: DocumentationNew/mkdocs.yml # Path to MkDocs config -# Optionally build your docs in additional formats such as PDF and ePub +# Enable additional output formats (optional, MkDocs natively supports HTML) formats: - - epub - pdf - - htmlzip + - epub python: install: - - requirements: Documentation/requirements.txt + - requirements: DocumentationNew/requirements.txt diff --git a/DocumentationNew/docs/contributions.md b/DocumentationNew/docs/contributions.md new file mode 100644 index 00000000..791c489a --- /dev/null +++ b/DocumentationNew/docs/contributions.md @@ -0,0 +1,101 @@ +# Contributor's Guide + +lib3mf is an open-source project. + +Contributions are welcome, and we are always looking for people who can improve the implementation of the specification and extensions of 3MF. + +You can also contribute by reporting bugs in the [Issue tracker](https://github.com/3MFConsortium/lib3mf/issues), helping review pull requests, participating in discussions about issues, and more. + +--- + +## Filing Issues + +When filing an [issue](https://github.com/3MFConsortium/lib3mf/issues) to report errors or problems, make sure to answer these five questions: + +1. **Which version of lib3mf are you using?** + - The API call `lib3mf_getlibraryversion` reveals lib3mf's version number. + - **Windows only:** The properties of lib3mf's binary contain version information (e.g., right-click on the DLL → Properties → Details). + +2. **Which operating system are you using?** +3. **What did you do?** +4. **What did you expect to see?** +5. **What did you see instead?** + +When contributing to this repository, please first discuss the change you wish to make via an issue with the [maintainers](#maintainers). This way, we can ensure that there is no overlap between contributions or development work by the 3MF consortium itself. + +--- + +## Submitting a Pull Request + +When ready to contribute, **fork** this repository and submit a **pull request** that references the issue it resolves. Be sure to include a clear and detailed description of the changes you've made so that we can verify them and eventually merge. + +lib3mf follows the [git-flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) branching model. +New developments are integrated into the [develop](https://github.com/3MFConsortium/lib3mf/tree/develop) branch. +lib3mf's maintainers will create releases from the develop branch when appropriate. + +--- + +## Maintainers + +Maintainers are responsible for responding to pull requests and issues, as well as guiding the direction of the project. + +We currently have two maintainers: + +- **Alexander Oster** - [alexander.oster@autodesk.com](mailto:alexander.oster@autodesk.com) +- **Martin Weismann** - [martin.weismann@autodesk.com](mailto:martin.weismann@autodesk.com) + +If you've established yourself as an impactful contributor to the project and are willing to take on extra work, we'd love to have your help maintaining it! +Email the current maintainers for details. + +--- + +## Building lib3mf from Source + +1. **Clone the repository** + ```sh + git clone https://github.com/3MFConsortium/lib3mf + ``` +2. **Enter local checkout** + ```sh + cd lib3mf + ``` +3. **Initialize the [googletest](https://github.com/google/googletest) submodule** + ```sh + git submodule update --init + ``` +4. **Generate project files using CMake** + Use the scripts in the **[cmake](cmake)** folder: + - **Windows:** Run `GenerateVS2017.bat` + - **Linux/Mac:** Run `GenerateMake.sh` + - To specify custom [CMake generators](https://cmake.org/cmake/help/v3.0/manual/cmake-generators.7.html), define your own target. + + This will create a `build/` folder containing the appropriate project files. + +5. **Build the projects** + - **Windows:** + 1. Open the **Visual Studio Solution** in the `build/` folder. + 2. Build the solution. + 3. Select the project you want to run as the "Start-Up Project." + 4. Run/debug it in Visual Studio. + + - **Linux/Mac:** + 1. Navigate to the `build/` folder. + 2. Run: + ```sh + make + ``` + 3. Run/debug the compiled binaries. + +--- + +## How to Develop lib3mf + +lib3mf is based on the **hourglass pattern** for software components and uses the +[Automatic Component Toolkit (ACT)](https://github.com/Autodesk/AutomaticComponentToolkit/) to simplify development. + +lib3mf's goal is to run on **Windows, Linux, and macOS**, with most of its code being **platform-independent**. + +!!! note "" + The contents of this page have been largely copied from + [https://github.com/3MFConsortium/lib3mf/blob/master/CONTRIBUTING.md](https://github.com/3MFConsortium/lib3mf/blob/master/CONTRIBUTING.md). + If you find any information to be outdated, feel free to let us know. diff --git a/DocumentationNew/docs/images/3mf.png b/DocumentationNew/docs/images/3mf.png new file mode 100644 index 00000000..3ac27a57 Binary files /dev/null and b/DocumentationNew/docs/images/3mf.png differ diff --git a/DocumentationNew/docs/images/dot-3mf.png b/DocumentationNew/docs/images/dot-3mf.png new file mode 100644 index 00000000..b14576fa Binary files /dev/null and b/DocumentationNew/docs/images/dot-3mf.png differ diff --git a/DocumentationNew/docs/images/olive.png b/DocumentationNew/docs/images/olive.png new file mode 100644 index 00000000..059fed8a Binary files /dev/null and b/DocumentationNew/docs/images/olive.png differ diff --git a/DocumentationNew/docs/index.md b/DocumentationNew/docs/index.md new file mode 100644 index 00000000..be0c6edf --- /dev/null +++ b/DocumentationNew/docs/index.md @@ -0,0 +1 @@ +# Welcome to lib3mf Documentation diff --git a/DocumentationNew/docs/license.md b/DocumentationNew/docs/license.md new file mode 100644 index 00000000..0fd6cbe6 --- /dev/null +++ b/DocumentationNew/docs/license.md @@ -0,0 +1,28 @@ +# License (BSD-2-Clause) + +© 2019 3MF Consortium +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions, and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, this + list of conditions, and the following disclaimer in the documentation and/or + other materials provided with the distribution. + +--- + +## **Disclaimer** +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, +INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/DocumentationNew/docs/pdf-styles.css b/DocumentationNew/docs/pdf-styles.css new file mode 100644 index 00000000..a3c3147c --- /dev/null +++ b/DocumentationNew/docs/pdf-styles.css @@ -0,0 +1,13 @@ +/* ============================= */ +/* 📄 Fix List Indentation in PDFs */ +/* ============================= */ + +ol, ul { + margin-left: 20px; /* Adjust list margin */ + padding-left: 20px; /* Add padding to align properly */ +} + +ol ol, ol ul, ul ol, ul ul { + margin-left: 30px; /* Ensure nested lists are indented properly */ + padding-left: 30px; +} \ No newline at end of file diff --git a/DocumentationNew/mkdocs.yml b/DocumentationNew/mkdocs.yml new file mode 100644 index 00000000..982f6c7f --- /dev/null +++ b/DocumentationNew/mkdocs.yml @@ -0,0 +1,94 @@ +site_name: lib3mf documentation +site_url: https://lib3mf.readthedocs.io/ +site_author: 3MF Consortium +site_description: "Official documentation for lib3mf" + +repo_url: https://github.com/3MFConsortium/lib3mf +edit_uri: "" + +theme: + name: material + logo: images/dot-3mf.png + favicon: images/3mf.png + features: + - navigation.tabs + - navigation.sections + - navigation.instant + - navigation.expand + - navigation.top + - search.highlight + - content.code.copy # Copy button for code blocks + - content.code.annotate + palette: + - scheme: default # Light mode + primary: grey + accent: deep-orange + toggle: + icon: material/weather-night # Moon icon for dark mode + name: Switch to dark mode + - scheme: slate # Dark mode + primary: grey + accent: light-blue + toggle: + icon: material/weather-sunny # Sun icon for light mode + name: Switch to light mode + font: + text: Roboto + code: Roboto Mono + icon: + repo: fontawesome/brands/github + +nav: + - Home: index.md + - Getting Started: + - Installation: installation.md + - Usage: usage.md + - Reference: + - API Overview: api.md + - Advanced Topics: advanced.md + - About: + - License: license.md + - Contributing: contributions.md +extra: + generator: false + social: + - icon: fontawesome/brands/github + link: https://github.com/3MFConsortium/lib3mf + toggle: + icon: material/weather-night # Night mode (moon) + name: Switch to dark mode + position: right # Moves toggle to the rightmost position + +extra_css: + - pdf-styles.css + +plugins: + - search + - with-pdf: + output_path: "../lib3mf_documentation.pdf" + cover: true + cover_logo: images/dot-3mf.png + cover_title: "lib3mf documentation" + toc_title: "Table of Contents" + author: "3MF Consortium" + cover_subtitle: "" + copyright: "v2.4.1-alpha" + stylesheets: + - pdf-styles.css + - minify: + minify_html: true + - table-reader # Enables CSV and table support + - mkdocs-video # Adds video embedding + +markdown_extensions: + - admonition + - pymdownx.superfences + - pymdownx.tabbed + - pymdownx.highlight + - pymdownx.emoji + - pymdownx.extra + - pymdownx.tasklist + - pymdownx.details + - pymdownx.keys + - toc: + permalink: "#" diff --git a/DocumentationNew/requirements.txt b/DocumentationNew/requirements.txt new file mode 100644 index 00000000..2b3f92f1 --- /dev/null +++ b/DocumentationNew/requirements.txt @@ -0,0 +1,10 @@ +# MkDocs and Material Theme +mkdocs-material + +# Plugins for Extra Features +mkdocs-material[plugins] # Enables all recommended plugins +mkdocs-macros-plugin # Allows using macros in Markdown files +mkdocs-minify-plugin +mkdocs-video +mkdocs-with-pdf +mkdocs-table-reader-plugin \ No newline at end of file