ASP.NET Docs

This project is part of ASP.NET 5. You can find samples, documentation and getting started instructions for ASP.NET 5 at the Home repo.

This repo contains documentation for ASP.NET 5. The documentation is built using Sphinx and reStructuredText, and then hosted by ReadTheDocs.

Building the Docs

To build the docs, you will need to install python (version 2 or higher). If you are running Windows, you will want to add the Python install folder and the \Scripts\ folder to your PATH environment variable.

To install Sphinx, open a command prompt and run:

pip install sphinx

This project is also using a custom theme from ReadTheDocs, which you can install with:

pip install sphinx_rtd_theme

You should now be able to navigate to the docs folder and run

make html

which should generate the documentation in the _build folder. Open the _build/html/index.html file to view the generated documentation.

You can also install sphinx-autobuild which will run a local webserver and automatically refresh whenever changes to docs files are detected. To do so, first install sphinx-autobuild:

pip install sphinx-autobuild

Then run it from the root of the project with

sphinx-autobuild docs docs/_build/html

Note that you may need to run 'make html' once before sphinx-autobuild will serve the docs correctly. Also, there seems to be an encoding issue in one of the CSS files in the theme that may cause Python to throw an exception when trying to serve the file. You can work around this issue by editing the cp1252.py file (most likely in C:\Python34\Lib\encodings\ on Windows). Modify the IncrementalDecoder as follows:

class IncrementalDecoder(codecs.IncrementalDecoder):
		def decode(self, input, final=False):
    		return codecs.charmap_decode(input,'ignore',decoding_table)[0]

This should allow the CSS file to be loaded, but may result in icons being rendered improperly. A proper fix will likely involve confirming the encoding used by the CSS file for the RTD theme.

If contributing new documentation content, please review the Sphinx Style Guide.

Adding Content

In addition to the style guide, articles should be organized into logical groups or sections. Each section should be given a named folder (e.g. /yourfirst). Within each section, each article should also have its own folder, within which the article.rst file resides. Images and other static resources (code samples, etc.) should be placed in a _static folder within the article folder.

Example Structure

docs
	/yourfirst
		/fundamentalconcepts
			/_static
				about-page.png
				add-config.png
				...
			fundamentalconcepts.rst
		/yourfirstaspnetapplication
			/_static
				about-page.png
				add-api-controller.png
				...
			yourfirstaspnetapplication.rst

Note: Sphinx will automatically fix duplicate image names, such as the about-page.png files shown above. There is no need to try to ensure uniqueness of static files beyond an individual article.

Author information should be placed in the _authors folder following the example of steve-smith.rst. Place photos in the photos folder - size them to be no more than 125px wide or tall.