/api-doc-tools

Documentation toolchain

Primary LanguageC#MIT LicenseMIT

mdoc and monodoc

This repository contains the source for Mono's documentation toolchain.

Compiling

Dependencies

This repository uses submodules, so firstly, you have several options:

  • You can include all submodules when you initially clone: git clone --recursive https://github.com/mono/api-doc-tools.git
  • If you already have it local, you can use git submodule update --init --recursive
  • If you have all CLI dependencies (see below), you can make prepare

Visual Studio

On windows, you can build and compile apidoctools.sln. And you can run unit tests if you have NUnit installed. If you use Visual Studio for Mac, you can use its built-in support for NUnit tests to also run tests.

CLI

If you've got make and mono installed, you can run make prepare all check to do a release build and run the full test suite (which for mdoc includes more than just the nunit tests). The available targets are:

  • prepare: initializes the submodules, and restores the nuget dependency of NUnit
  • all: compiles everything
  • check: runs unit tests for monodoc and mdoc
  • check-mdoc: runs only mdoc tests
  • check-monodoc: runs only monodoc tests

You can also control some parameters from the command line:

If you want to compile in debug mode: make all CONFIGURATION=Debug

Troubleshooting

WSL

Make sure you are at least on 16.04 (Xenial). You can check which version is currently installed by running the command lsb_release -a.

If you are running an older version (for example, if you originally installed WSL before the creator's update) and need to upgrade, you can run the following commands:

  • sudo do-release-upgrade ... this updates the version of Ubuntu. Please note, this will likely disable any external package sources, such as the one added when installing Mono.
  • Once you're done with that, then you just need to update apt-get
    • Add back Mono's package repository source, as described in the download instructions.
    • sudo apt-get update
    • sudo apt-get upgrade
    • sudo apt-get dist-upgrade

With that run ... you should be able to run the build locally.

Linux

The following script will prepare, clone, and run a full build with tests of mdoc on an unbuntu docker container.

apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF  
echo "deb http://download.mono-project.com/repo/ubuntu trusty main" | tee /etc/apt/sources.list.d/mono-official.list

apt-get update
apt-get install tzdata nuget -y --allow-unauthenticated
apt-get install git make mono-devel mono-vbnc ca-certificates-mono wget fsharp -y

wget -q 'http://mxr.mozilla.org/seamonkey/source/security/nss/lib/ckfw/builtins/certdata.txt?raw=1' -O "/tmp/certdata.txt" 
mozroots --import --ask-remove --file /tmp/certdata.txt


git clone https://github.com/mono/api-doc-tools
cd api-doc-tools
make prepare all check

Please review mono's installation guide if you are using a different flavor of linux.