-
Notifications
You must be signed in to change notification settings - Fork 597
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Spruce up the main README and add "Building_the_docs" (#3991)
For the upcoming DevDays, I wanted to spruce up our main README to make it easier to find info, and I wrote a new guide for how to locally build the documentation. Signed-off-by: Larry Gritz <[email protected]>
- Loading branch information
Showing
2 changed files
with
183 additions
and
63 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,5 @@ | ||
| <!-- SPDX-License-Identifier: CC-BY-4.0 --> | ||
| <!-- Copyright Contributors to the OpenImageIO Project. --> | ||
| <p align="center"> | ||
| <img src="ASWF/logos/openimageio-horizontal-gradient.png"> | ||
| </p> | ||
|
|
@@ -11,6 +13,11 @@ | |
| Introduction | ||
| ------------ | ||
|
|
||
| **Mission statement**: OpenImageIO is a toolset for reading, writing, and | ||
| manipulating image files of any image file format relevant to VFX / animation | ||
| via a format-agnostic API with a feature set, scalability, and robustness | ||
| needed for feature film production. | ||
|
|
||
| The primary target audience for OIIO is VFX studios and developers of | ||
| tools such as renderers, compositors, viewers, and other image-related | ||
| software you'd find in a production pipeline. | ||
|
|
@@ -64,92 +71,88 @@ OpenImageIO consists of: | |
|
|
||
|
|
||
|
|
||
| Licensing | ||
| --------- | ||
| 🏢 Project administration and Licensing | ||
| --------------------------------------- | ||
|
|
||
| OpenImageIO is (c) Copyright Contributors to the OpenImageIO project. | ||
|
|
||
| OpenImageIO is distributed using primarily the Apache 2.0 license -- see the | ||
| [LICENSE.md](LICENSE.md) file for details. The documentation is licensed | ||
| under the [Creative Commons Attribution 4.0 Unported | ||
| License](http://creativecommons.org/licenses/by/4.0/). A small amount of code | ||
| imported from other projects, and also some pre-July-2023 code that has not | ||
| yet been relicensed under Apache-2.0, is covered by other compatible licenses | ||
| -- see [THIRD-PARTY](THIRD-PARTY.md) file for details. | ||
|
|
||
| The plain English bottom line is that OpenImageIO is free, as well as | ||
| freely modifiable and redistributable (in both source and binary form). | ||
| You may use part or all of it in your own applications, whether | ||
| proprietary or open, free or commercial. Using it in a commercial or | ||
| proprietary application DOES NOT obligate you to pay us, or to use any | ||
| particular licensing terms in your own application. | ||
|
|
||
| Some code and resources are distributed along with OIIO that have highly | ||
| compatible, though slightly different, licenses (generally MIT or Apache). | ||
| See the PDF documentation Acknowledgements section, and the | ||
| [THIRD-PARTY](THIRD-PARTY.md) file for details. | ||
| For original code, we use the [Apache-2.0 license](LICENSE.md), and for | ||
| documentation, the [Creative Commons Attribution 4.0 Unported | ||
| License](http://creativecommons.org/licenses/by/4.0/). In 2023 we asked | ||
| historical users to [relicense](RELICENSING.md) from the original BSD-3-clause | ||
| license to Apache-2.0, and over 99.75% of lines of code have been relicensed | ||
| to Apache-2.0. A small amount of code incorporated into this repository from | ||
| other projects are covered by compatible [third-party open source | ||
| licenses](THIRD-PARTY.md). | ||
|
|
||
| The OpenImageIO project is part of the [Academy Software | ||
| Foundation](https://www.aswf.io/), a part of the Linux Foundation formed in | ||
| collaboration with the Academy of Motion Picture Arts and Sciences. The | ||
| [Technical Charter](aswf/Technical-Charter.md) and [Project | ||
| Governance](GOVERNANCE.md) explain how the project is run, who makes | ||
| decisions, etc. Please be aware of our [Code of Conduct](CODE_OF_CONDUCT.md). | ||
|
|
||
| Building and Installation | ||
| ------------------------- | ||
|
|
||
| Please read the [INSTALL.md](INSTALL.md) file for detailed instructions on | ||
| how to build and install OpenImageIO. | ||
| 💁 User Documentation | ||
| --------------------- | ||
|
|
||
| If you build with `EMBEDPLUGINS=0`, remember that you need to set the | ||
| environment variable `OIIO_LIBRARY_PATH` to point to the 'lib' directory | ||
| where OpenImageIO is installed, or else it will not be able to find the | ||
| plugins. | ||
| [OpenImageIO Documentation on ReadTheDocs](https://openimageio.readthedocs.io/) | ||
| is the best place to start if you are interested in how to use OpenImageIO, | ||
| its APIs, its component programs (once they are built). There is also a [PDF | ||
| version](https://readthedocs.org/projects/openimageio/downloads/pdf/latest/). | ||
|
|
||
|
|
||
| Documentation | ||
| ------------- | ||
| 👷 Building and installing OpenImageIO | ||
| -------------------------------------- | ||
| - [Build and installation instructions](/INSTALL.md) for OpenImageIO. Such | ||
| as it is. This could use some work, particularly for Windows. | ||
|
|
||
| The primary user and programmer documentation can be found | ||
| on [openimageio.readthedocs.io](https://openimageio.readthedocs.io/en/latest/) | ||
| as html or as [PDF](https://readthedocs.org/projects/openimageio/downloads/pdf/latest/). | ||
|
|
||
|
|
||
| Contact & reporting problems | ||
| ---------------------------- | ||
| 🚑 Contact & reporting problems | ||
| ------------------------------- | ||
|
|
||
| Simple "how do I...", "I'm having trouble", or "is this a bug" questions are | ||
| best asked on the [oiio-dev developer mail | ||
| list](https://lists.aswf.io/g/oiio-dev). | ||
| That's where the most people will see it and potentially be able to answer | ||
| your question quickly (more so than a GH "issue"). | ||
| list](https://lists.aswf.io/g/oiio-dev). That's where the most people will see | ||
| it and potentially be able to answer your question quickly (more so than a GH | ||
| "issue"). For quick questions, you could also try the [ASWF | ||
| Slack](https://slack.aswf.io) `#openimageio` channel. | ||
|
|
||
| Bugs, build problems, and discovered vulnerabilities that you are relatively | ||
| certain is a legit problem in the code, and for which you can give clear | ||
| instructions for how to reproduce, should be [reported as | ||
| certain is a legit problem in the code, and **for which you can give clear | ||
| instructions for how to reproduce**, should be [reported as | ||
| issues](https://github.com/OpenImageIO/oiio/issues). | ||
|
|
||
| If confidentiality precludes a public question or issue, you may contact us | ||
| privately at [[email protected]]([email protected]), or for | ||
| security-related issues [[email protected]]([email protected]). | ||
|
|
||
|
|
||
| Contributing | ||
| ------------ | ||
| 🔧 Contributing and developer documentation | ||
| ------------------------------------------- | ||
|
|
||
| OpenImageIO welcomes code contributions, and [nearly 200 people](CREDITS.md) | ||
| have done so over the years. We take code contributions via the usual GitHub | ||
| pull request (PR) mechanism. Please see [CONTRIBUTING](CONTRIBUTING.md) for | ||
| detailed instructions. | ||
|
|
||
|
|
||
| Web Resources | ||
| ------------- | ||
|
|
||
| * Main web page: http://www.openimageio.org | ||
|
|
||
| * GitHub page: http://github.com/OpenImageIO/oiio | ||
|
|
||
| * Developer mail list subscriptions and archives: | ||
| https://lists.aswf.io/g/oiio-dev | ||
|
|
||
| * ASWF Slack: https://slack.aswf.io | ||
| (look for the `#openimageio` channel) | ||
|
|
||
| * Biweekly TSC meetings are on the ASWF Calendar: https://www.aswf.io/meeting-calendar/ | ||
| (click on the OpenImageIO meeting entries, every second Monday, to get the Zoom link, anyone may join) | ||
| pull request (PR) mechanism. | ||
|
|
||
| * [CONTRIBUTING](CONTRIBUTING.md) has detailed instructions about the | ||
| development process. | ||
| * [RELEASING](RELEASING.md) explains our policies and procedures for making | ||
| releases. We have a major, possibly-compatibility-breaking, release annually | ||
| in September/October, and minor bug fix and safe feature addition release at | ||
| the beginning of every month. | ||
| * [Building the docs](src/doc/Building_the_docs.md) has instructions for | ||
| building the documentation locally, which may be helpful if you are editing | ||
| the documentation in nontrivial ways and want to preview the appearance. | ||
|
|
||
|
|
||
| ☎️ Communications channels and additional resources | ||
| -------------------------------------------------- | ||
|
|
||
| * [Main web page](http://www.openimageio.org) | ||
| * [GitHub project page](http://github.com/OpenImageIO/oiio) | ||
| * [Developer mail list](https://lists.aswf.io/g/oiio-dev) | ||
| * [ASWF Slack](https://slack.aswf.io) (look for the `#openimageio` channel) | ||
| * Biweekly Technical Steering Committee (TSC) Zoom meetings are on the [ASWF | ||
| Calendar](https://www.aswf.io/meeting-calendar/) (click on the OpenImageIO | ||
| meeting entries, every second Monday, to get the Zoom link, anyone may join) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| <!-- SPDX-License-Identifier: CC-BY-4.0 --> | ||
| <!-- Copyright Contributors to the OpenImageIO Project. --> | ||
|
|
||
| # Building the OpenImageIO documentation | ||
|
|
||
| The main OpenImageIO documentation can be read on [OpenImageIO Documentation | ||
| on ReadTheDocs](https://openimageio.readthedocs.io/). | ||
|
|
||
| But sometimes -- such as for developers who are editing the documentation -- | ||
| it is helpful to be able to build and preview it locally. These are the steps | ||
| required to build the documentation. | ||
|
|
||
| The main docs as they appear on ReadTheDocs consist of two parts: | ||
|
|
||
| - Individual class and function documentation that are in the comments | ||
| in the various public header files of OpenImageIO. | ||
| - All the explanatory text found in `src/doc/*.rst`, which is processed | ||
| by Sphinx to generate the final documentation, and which draw on the | ||
| header documentation that was extracted by Doxygen. | ||
|
|
||
|
|
||
| ## Building what you need to build the docs | ||
|
|
||
| To be able to fully build the documentation, there are some packages you | ||
| will need installed. | ||
|
|
||
| ### Python | ||
|
|
||
| You will need Python. | ||
|
|
||
|
|
||
| ### Doxygen | ||
|
|
||
| We don't use Doxygen for our final docs, but we do use it to generate some | ||
| intermediate files used by the Sphinx documentation (via the Breathe plugin), | ||
| so you'll need it installed. | ||
|
|
||
| You can read full build-from-source instructions for Doxygen | ||
| [here](https://www.doxygen.nl/manual/install.html), but that's unnecessary | ||
| for most users. There are several common ways to install via package | ||
| managers: | ||
|
|
||
| - Debian/Ubuntu/etc that use apt: `sudo apt install doxygen` | ||
| - RHEL/CentOS/Rocky/Alma/etc/ that use yum: `sudo yum install doxygen` | ||
| - Homebrew on macOS: `brew install doxygen` | ||
| - MacPorts on macOS: `sudo port install doxygen` | ||
|
|
||
|
|
||
| ### Sphinx and its plugins | ||
|
|
||
| Our main documentation uses Sphinx, and several extensions. The easiest way to | ||
| install it is via Python PIP: | ||
|
|
||
| - [Sphinx](https://www.sphinx-doc.org/) documentation generator: `pip install -U sphinx` | ||
| - [Breathe](https://breathe.readthedocs.io) plugin for Sphinx for combining with Doxygen: `pip install breathe` | ||
| - [Sphinx-tabs](https://sphinx-tabs.readthedocs.io) plugin: `pip install -U sphinx-tabs` | ||
| - [Furo](https://github.com/pradyunsg/furo) theme: `pip install furo` | ||
|
|
||
|
|
||
|
|
||
| ## Actually building the docs | ||
|
|
||
| The building of the documentation is separate from the main OpenImageIO | ||
| build system. | ||
|
|
||
| 1. First, build OpenImageIO itself. You should probably know how to do this | ||
| before you're writing documentation for other users. Note that the build | ||
| itself will generate a lot of temporary files (like object files) from the | ||
| compilation in the `build` subdirectory, and that will also be used as scratch space for building the documentation. | ||
|
|
||
| 2. Do the rest of these steps in src/doc: | ||
|
|
||
| cd src/doc | ||
|
|
||
| 3. Build the Doxygen intermediate files | ||
|
|
||
| # (still in the src/doc directory) | ||
| make doxygen | ||
|
|
||
| Don't worry about warnings. Only worry if you see errors. | ||
|
|
||
| You only need to redo this step if you do one of the following things: | ||
| - Edit any of the `.h` file from which documentation is extracted. In fact, | ||
| more specifically, you need to redo this step if you CHANGE any of the | ||
| doxygen-based documentation in the comments of the headers. | ||
| - Start a fresh build, change which branch you're working on, or in any | ||
| way delete your `build` directory. Remember, as pointed out above, that | ||
| this is where the documentation is built, so if it disappears, you have | ||
| to start over again. | ||
|
|
||
| 4. Build the Sphinx documentation | ||
|
|
||
| # (still in the src/doc directory) | ||
| make sphinx | ||
|
|
||
| You should see output that may spew some warnings (don't worry about | ||
| that) and should end with something that looks like this: | ||
|
|
||
| ... | ||
| dumping search index in English (code: en)... done | ||
| dumping object inventory... done | ||
| build succeeded, 63 warnings. | ||
|
|
||
| You need to redo this Sphinx step if you change any of the text | ||
| documentation in `src/doc/*.rst` is changed. Note that if you are only | ||
| changing the `.rst` files, there is no need to go all the way back to step | ||
| 3 to regenerate the Doxygen files. | ||
|
|
||
| 5. Where are my docs? | ||
|
|
||
| The HTML pages are in `../../build/sphinx` | ||
|
|
||
| Point your browser at `index.html` in that directory to view the docs. | ||
|
|
||
|
|
||
|
|
||
|
|