![Surreal Docs Banner](https://github.com/medelfor/surreal-docs/raw/master/readme/SurrealDocsBanner.png)

Documentation | Live-Demo | Medelfor | Store | Known Issues | Twitter | Roadmap

*** If you haven't yet used Surreal Docs, please take our brief [6-question survey](https://forms.gle/5q4CrCMTTXjS9qdA6 "Short survey for those who didn't use Surreal Docs") to help us understand our users better. If you're already familiar with our software, please take our [extended survey](https://forms.gle/gGojHBSS3o7SrDGC6 "Brief survey") with 15 questions to help us improve. Your feedback is valuable to us! *** Surreal Docs is a comprehensive documentation generation system designed specifically for Unreal Engine-powered projects. It generates documentation for both C++ and Blueprint API references, and provides users with the ability to create custom pages using a feature-rich dialect of Markdown. Additionally, Surreal Docs seamlessly integrates with Surreal Cloud, our online documentation hosting platform, allowing users to easily share their documentation with others. Finally, Surreal Docs has a deep understanding of all UE-specific C++ features and Blueprints, what allows it to cleverly interweave C++ and BP entities in the resulting documentation. The latest version of Surreal Docs is `1.1.1` **Table of Contents** - [Install](https://github.com/medelfor/surreal-docs/raw/master/#install) - [Quickstart](https://github.com/medelfor/surreal-docs/raw/master/#quickstart) - [OS and Unreal Engine Compatibilty](https://github.com/medelfor/surreal-docs/raw/master/#os-and-unreal-engine-compatibilty) - [Telemetry](https://github.com/medelfor/surreal-docs/raw/master/#telemetry) - [Privacy](https://github.com/medelfor/surreal-docs/raw/master/#privacy) - [Build](https://github.com/medelfor/surreal-docs/raw/master/#build) - [Issues and Support](https://github.com/medelfor/surreal-docs/raw/master/#issues-and-support) - [Pull requests](https://github.com/medelfor/surreal-docs/raw/master/#pull-requests) - [What we're doing right now](https://github.com/medelfor/surreal-docs/raw/master/#what-were-doing-right-now) - [Performance](https://github.com/medelfor/surreal-docs/raw/master/#performance) - [FAQ](https://github.com/medelfor/surreal-docs/raw/master/#faq) - [License](https://github.com/medelfor/surreal-docs/raw/master/#license) - [Surreal Ecosystem](https://github.com/medelfor/surreal-docs/raw/master/#surreal-ecosystem) ## Install To install Surreal Docs please download the latest installer from the Releases page and run it. Note also that in order to work Surreal Docs requires Microsoft Visual Studio to be installed on your machine. You can find more info about the installation process on the ["Installation"](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/installation "Installation process description") page of [Surreal Docs documentation](https://docs.medelfor.com/medelfor/surreal-docs "Surreal Docs documentation"). ## Quickstart Surreal Docs installer installs the Surreal Docs CLI, so you would be able to run Surreal Docs from the command line. In order to generate documentation for your Unreal Engine project, please open a console of your choice (Windows CMD, PowerShell, etc.) and navigate to the root directory[1] of your Unreal Engine project. When done, please run the following command in your console: ``` surdocs init ``` It will invoke the initialization screen where you can set options of your project and the documentation you are going to generate. Surreal Docs will detect and set most settings automatically, but you should review them and update if necessary. **IMPORTANT**: you have to choose an \*Editor target, since Surreal Docs cannot be run without UE editor. On the same screen you should choose the project modules for which you want to generate documentation. After everything's finished, please click the "Done" button and wait until Surreal Docs will set up your project. Note that Surreal Docs changes the `.uproject` file, so before changing it, the system makes a backup of the file and saves it in the same directory. The `surdocs init` must be run only once, on the initial setup of the project. If `surdocs init` has finished successfully, then please run the next command: ``` surdocs generate ``` It will invoke the generation screen and start generating documentation for your Unreal Engine project. You will be able to observe the progress and will see error's details if something goes wrong. Note that the first time you run `surdocs generate` the generation will take some extra time, since Surreal Docs needs to compile the plugin it installs in order to link with Unreal Engine. In order to deploy your documentation to Surreal Cloud, add the `--deploy` option to your command. This option specifies organization and the project where the documentation should go to. You can find more info on the [generate page](https://github.com/medelfor/surreal-docs/raw/master/docs/cli/generate "generate description"). ``` surdocs generate --deploy=/ ``` Note that this functionality is available for those users only who own an active Surreal Cloud, Surreal Cloud+ or Surreal Cloud Pro subscription. More about Surreal Cloud [here](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/surreal-cloud "Surreal Cloud"). You can find more info that will help you get up to speed on the ["Quickstart"](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/quickstart "Quickstart") page. *** [1] The directory that contains the `.uproject` file. ## OS and Unreal Engine Compatibilty Surreal Docs is intended to be used with 64-bit Windows systems. Unreal Engine support is as follows: | Unreal Engine version | Support [1] | |-----------------------|--------------------------------------------------------| | Less than 4.27 | Not tested. No support available for potential issues. | | 4.27 | Yes | | 5.0 | Yes | | 5.1 | Yes | | 5.2 | Yes | | 5.3 (incl. preview) | Not tested. Support is coming soon [2] | You can find more info about OS and Unreal Engine compatibility on the ["Supported operating systems and Unreal Engine versions"](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/os-and-ue-support "Supported operating systems and Unreal Engine versions") page. *** [1] You can find more info about supported Unreal Engine features on the ["Support of the Unreal Engine features"](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/ue-features-support "Support of the Unreal Engine features") page. [2] Support for 5.3 release will be added as soon as the version is released. ## Telemetry By default, Surreal Docs collects and sends us anonymized usage data, such as ID of your machine, version of Surreal Docs you're running, etc. In order to disable it, please provide `--no-tele` argument when starting Surreal Docs CLI. It will disable the telemetry for the time current command is running. Example: ``` surdocs --no-tele generate out ``` Note however that by letting Surreal Docs collect anonymized usage data you help the development process a lot. The collection of this data is governed by Surreal Docs EULA that can be found in the `LICENSE` file. You can find more info about global options available in Surreal Docs CLI on the ["Global options"](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/cli/global-options "Global options") page. ## Privacy Your privacy is important to us! While you can read more about your privacy when using Surreal Docs in the EULA, you can be sure that we **do not**, under any circumstances, collect or send to ourselves (or any 3rd parties) neither the source code of your project nor the generated documentation[1]. *** [1] We do send your documentation (but not source code) to our servers in case you've run deployment of the docs to [Surreal Cloud](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/surreal-cloud "Surreal Cloud"). ## Build We're working on the build instructions and will publish them soon. ## Issues and Support You can find more info regarding troubleshooting on the ["Troubleshooting"](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/troubleshooting "Troubleshooting") page. If you believe there's something wrong with the product, please create an issue in this repository. You can also contact [support@medelfor.com](https://github.com/medelfor/surreal-docs/raw/master/mailto:support@medelfor.com "Support email") or [@medelfor](https://twitter.com/medelfor "@medelfor"). We're glad to help! You can browse list of issues already being in work in our YouTrack [here](https://issues.internal.medelfor.com/youtrack/issues?q=project:%20%7BSurreal%20Docs%7D "Surreal Docs WIP issues"). ## Pull requests Please, feel free to submit your changes to the Surreal Docs Source Code in pull requests for this repository. We deeply appreciate any contributions made by our users! ## What we're doing right now We're working on the [1.2.0](https://medelfor.com/roadmap/surreal-docs) release as well as doing general maintenance. ## Performance At this moment, Surreal Docs is best suited to work with medium-sized projects of up to 100,000 lines of code (LOC) of header files. The volume of `.cpp` files does not matter. Larger projects are supported but require more time to be processed, and will have a bigger memory footprint. ### Memory issues Regarding memory issues, during the initial "Loading documentation tree" stage, there are reports of a substantial memory consumption spike. We are aware of this problem and are working to fix it. ## FAQ ### Is Surreal Docs usage free of charge? If you're an individual that doesn't intend to use Surreal Docs with crypto-related projects, then yes, for you Surreal Docs is free of charge. If you represent a legal entity that doesn't intend to use Surreal Docs with crypto-related projects and whose revenue for the last year is less than US $100,000, then yes, for your legal entity Surreal Docs is free of charge. Compare different [plans](https://medelfor.com/products/surreal-docs#pricing). Consult the [License](https://github.com/medelfor/surreal-docs/raw/master/#license) section or full EULA text in the `LICENSE` file for more details. ### How can I get rid of the watermarks on Blueprint function images and warnings in the footer? A paid Surreal Docs license is required in order to remove watermarks and free-warnings in the footer. A paid version also allows you to set company and project logos and gives several other advantages. Compare different plans [here](https://medelfor.com/products/surreal-docs#pricing). Check out ["Product activation"](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/product-activation "Product activation") page to learn how to register your copy of the product. ### What's the best way to host documentation generated by Surreal Docs? We've built Surreal Cloud - our documentation hosting specifically for Surreal Docs. Enjoy various features, including versioning, seamless integration with Surreal Docs, pretty/persistent links, continued support and others. Check out more information about Surreal Cloud and pricing [here](https://medelfor.com/products/surreal-cloud#pricing). ### Where do I download Surreal Docs You can download Surreal Docs installer from our [website](https://medelfor.com/products/surreal-docs). ### Is there support for the Verse programming language? There's no support for the Verse programming language at the moment, but it will be added as soon as the main-branch Unreal Engine gets Verse support. You can find more info about supported Unreal Engine features on the ["Support of the Unreal Engine features"](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/ue-features-support "Support of the Unreal Engine features") page. ### Can Surreal Docs be used to generate documentation for a plugin? You bet! Consult [this documentation page](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/generate-docs-for-plugins "Generation of documentation for a plugin") to find out how to do it. ### Can Surreal Docs be used with Blueprint-only projects? Absolutely, but note that Surreal Docs requires installed Microsoft Visual Studio no matter whether the project is Blueprint-only or not. You can find more details about it on the ["Generating documentation for Blueprint-only projects"](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/generate-docs-for-blueprint-only-projects "Generating documentation for Blueprint-only projects") page. ### Can Surreal Docs be used without an UE-project? Currently, Surreal Docs cannot be used without an Unreal Engine project, but we plan to add an ability to generate documentation with no attachments to UE, BP or C++ in the nearest future. ### Is there a Linux version of Surreal Docs? No there's no Linux version of Surreal Docs, and there's no plans to implement one in the foreseen future. You can find more info about OS compatibility on the ["Supported operating systems and Unreal Engine versions"](https://docs.medelfor.com/medelfor/surreal-docs/latest/en-US/docs/os-and-ue-support "Supported operating systems and Unreal Engine versions") page. ## License Surreal Docs is published under a proprietary license full text of which can be found in the `LICENSE` file. If you are an individual who intends to use Surreal Docs with Unreal Engine projects that are not related to cryptocurrencies, NFTs or blockchain then you can use Surreal Docs free of charge. If you represent a legal entity whose revenue for the last year (with today as the last day of the year) is less than US $100,000 and who intends to use Surreal Docs with Unreal Engine projects that are not related to cryptocurrencies, NFTs or blockchain then your legal entity can use Surreal Docs free of charge. In case of intention to use Surreal Docs with projects related to the cryptocurrencies (whether you are an individual or represent a legal entity), you must buy a Surreal Docs license that does not prohibit such usage, these licenses are marked with "Crypto". In case of intention to use Surreal Docs by a legal entity with the last year revenue bigger than US $100,000, the entity must buy a Surreal Docs license that does not prohibit such usage, these licenses are marked with "XL". The licenses can be acquired in [our store](https://store.medelfor.com "Medelfor Store"). Note that this is not a legal advice, please consult with your lawyer on details of the license agreement or contact [sales@medelfor.com](https://github.com/medelfor/surreal-docs/raw/master/mailto:sales@medelfor.com "Sales Team") if you have any questions about licensing of Surreal Docs. ## Surreal Ecosystem If you need to share your docs on the internet, or privately with the team check out our Surreal Cloud product series which makes it easy for developers to share their documentation with others. We've got a solution for any team, any use case and in every price range!

[Surreal Cloud](https://medelfor.com/#surreal-cloud "Surreal Cloud") - a serverless and auto-scaling cloud hosting for public documentation. Surreal Cloud is the easiest way to make your documentation available to everyone on the internet. Starts at $6.99/month (excl. VAT/GST).

[Surreal Cloud+](https://medelfor.com/#surreal-cloud-plus "Surreal Cloud+") - a Medelfor's cloud for public and private documentation. Surreal Cloud+ is the best way to share your documentation privately with your team. Starts at $14.99/month (excl. VAT/GST).

[Surreal Cloud Pro](https://medelfor.com/#surreal-cloud-pro "Surreal Cloud Pro") - the pinnacle of Surreal Cloud technology. Includes an on-premises variant of Surreal Cloud and the online cloud for private and public documentation. Surreal Cloud Pro is the perfect choice for companies who want to share their documentation within the organization. Starts at $39.99/month (excl. VAT/GST). Any Surreal Cloud solution integrates 100% seamlessly with Surreal Docs. ![Surreal Ecosystem Promo Banner](https://github.com/medelfor/surreal-docs/raw/master/readme/SurrealDocsSampleDocsPromo.png) ***

Documentation | Live-Demo | Medelfor | Store | Known Issues | Twitter | Roadmap

Thank you for using Medelfor products!