Autofac Documentation
Usage and API documentation for Autofac and integration libraries.
Check out the Autofac documentation at docs.autofac.org!
Updating the User Documentation Site
User documentation is viewable at
https://docs.autofac.org (a CNAME to
https://autofac.readthedocs.io). It is stored
in the /docs
folder in this source repo.
To build the docs and see them locally, you need to follow the Getting Started docs on Read The Docs so you get Python and Sphinx installed.
The docs are written in reStructuredText, which is very similar to Markdown but not quite. References below.
Updates to the documentation checked into the /docs
folder will automatically
propagate to Read The Docs. No build or separate push is required.
There is support for converting PlantUML (.puml) documents into PNG images for
easier diagramming. Run npm watch
to start the generation. Diagrams only get
generated on change and will not be rebuilt/regenerated without a change.
Building
- Install Python 3.x
- Install Sphinx:
pip install sphinx sphinx-autobuild
- Build the docs after you edit them. There should be NO errors or warnings:
make html
References
- ReStructured Text Quick Start
- ReStructured Text Quick Reference
- ReStructured Text Cheat Sheet
- ReStructured Text Primer
- Sphinx Markup Constructs
- ReadTheDocs Getting Started
Updating API Documentation
The API documentation is hosted on autofac.github.com
and the rendered/built docs are in there. This repository has the project that enables building the doc (a manual process) but publishing is a separate step.
The Placeholder
project holds references to the various Autofac packages to document. Use that as the basis for gathering the list of doc sources.
Adding/Updating Doc Sources
- Add or update the NuGet package to the
Placeholder
project. - Open the
app.config
for thePlaceholder
project and copy the assembly binding redirects to the appropriate location inDocumentation.shfbproj
. These are required for the documentation project to obey redirects.
Building the Documentation
Run msbuild Documentation.proj
to kick off the build. This will restore required NuGet packages, build the Placeholder
project, and run documentation on the Autofac referenced assemblies. You may need to install the Visual Studio 2017 build tools to get this to work. If you see errors/failing about unrecognized ToolsVersion
- that's the missing build tools.
The build generates a lot of warnings. These indicate where we're missing documentation. (If you're looking to submit a PR, better API docs is a good thing...)
Build output gets put in the artifacts
folder.
The contents of artifacts\doc\Website
is what gets copied to the autofac.github.com
repo.