{"id":18909318,"url":"https://github.com/mono/api-doc-tools","last_synced_at":"2025-04-04T19:11:28.731Z","repository":{"id":38153562,"uuid":"69486626","full_name":"mono/api-doc-tools","owner":"mono","description":".NET Reference API Toolchain","archived":false,"fork":false,"pushed_at":"2024-08-15T11:52:53.000Z","size":26622,"stargazers_count":67,"open_issues_count":96,"forks_count":52,"subscribers_count":52,"default_branch":"main","last_synced_at":"2024-08-16T09:08:14.457Z","etag":null,"topics":["documentation-toolchain","dotnet","ecmaxml","mdoc","mono","monodoc"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mono.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-28T17:20:57.000Z","updated_at":"2024-08-19T04:26:20.859Z","dependencies_parsed_at":"2023-02-17T21:46:07.034Z","dependency_job_id":"8498be82-7f85-460b-924c-d8780ff1a2bf","html_url":"https://github.com/mono/api-doc-tools","commit_stats":{"total_commits":972,"total_committers":62,"mean_commits":15.67741935483871,"dds":0.6646090534979423,"last_synced_commit":"a18cba51c16294f05eafeb08e0aae96abf0962a9"},"previous_names":[],"tags_count":114,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mono%2Fapi-doc-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mono%2Fapi-doc-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mono%2Fapi-doc-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mono%2Fapi-doc-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mono","download_url":"https://codeload.github.com/mono/api-doc-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234921,"owners_count":20905854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation-toolchain","dotnet","ecmaxml","mdoc","mono","monodoc"],"created_at":"2024-11-08T09:32:43.673Z","updated_at":"2025-04-04T19:11:28.716Z","avatar_url":"https://github.com/mono.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `mdoc`\n\nThis repository contains the source for the .NET API Reference toolchain ([used\n by learn.microsoft.com](https://learn.microsoft.com/en-us/teamblog/announcing-unified-dotnet-experience-on-docs#built-with-open-source-in-mind)) \n\n## Contribution Guide\n\nYou can read the [contribution guide](CONTRIBUTING.md) for information about coding standards, and (perhaps most importantly), information about writing [unit and integration tests](CONTRIBUTING.md#tests).\n\n## Compiling\n\n### Dependencies\n\nThis repository uses submodules, so firstly, you have several options:\n\n- You can include all submodules when you initially clone: `git clone --recursive https://github.com/mono/api-doc-tools.git`\n- If you already have it local, you can use `git submodule update --init --recursive`\n- If you have all CLI dependencies (see below), you can `make prepare`\n\n### Visual Studio\n\nOn windows, you can build and compile [`apidoctools.sln`](apidoctools.sln). And you can run unit tests if you have NUnit installed. If you use [Visual Studio for Mac](https://www.visualstudio.com/vs/visual-studio-mac/), you can use its built-in support for NUnit tests to also run tests.\n\n### CLI\nIf you've got `make` and `mono` installed, you can run `make prepare all check` in a _bash_ prompt 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:\n\n- `prepare`: initializes the submodules, and restores the nuget dependency of NUnit\n- `all`: compiles everything\n- `check`: runs unit tests for _monodoc_ and _mdoc_\n- `check-mdoc`: runs only _mdoc_ tests\n- `check-monodoc`: runs only _monodoc_ tests\n\nYou can also control some parameters from the command line:\n\nIf you want to compile in debug mode: `make all CONFIGURATION=Debug`  \n\nIf you are using WSL, use: `make all ENVIRONMENT=wsl`\n\nFeel free to open a pull request early in order to make it easy to ask questions during development, and for the maintainers to offer feedback.\n\n## Troubleshooting\n\n### Forcing Changes\n\nWhen you make certain kinds of changes, it can confuse _Make_'s dependency ... if you're running the test suite and it doesn't seem to be reflecting your changes, add the `-B` parameter to the `make` invocation, and it will force a rebuild of all targets.\n\n### WSL\n\nMake sure you are at least on 16.04 (Xenial). You can check which version is currently installed by running the command `lsb_release -a`.\n\nIf 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:\n\n- `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.\n- Once you're done with that, then you just need to update `apt-get`\n- Steps to set up the local WSL mdoc environment\n    - Install make `sudo apt-get install make`\n    - Install mono, Add back Mono's package repository source, as described in [the download instructions](https://www.mono-project.com/download/stable/#download-lin-ubuntu).\n    - Install Nuget `sudo apt-get install nuget`\n    - Install F# Compiler `sudo apt-get install mono-complete fsharp`\n\nWith that run ... you should be able to run the build locally using `make prepare all check`. \n\n### Linux\n\nThe following script will prepare, clone, and run a full build with tests of `mdoc` on an unbuntu docker container. \n\n```\napt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF  \necho \"deb http://download.mono-project.com/repo/ubuntu trusty main\" | tee /etc/apt/sources.list.d/mono-official.list\n\napt-get update\napt-get install tzdata nuget -y --allow-unauthenticated\napt-get install git make mono-devel mono-vbnc ca-certificates-mono wget fsharp -y\n\nwget -q 'http://mxr.mozilla.org/seamonkey/source/security/nss/lib/ckfw/builtins/certdata.txt?raw=1' -O \"/tmp/certdata.txt\" \nmozroots --import --ask-remove --file /tmp/certdata.txt\n\n\ngit clone https://github.com/mono/api-doc-tools\ncd api-doc-tools\nmake prepare all check\n```\n\nPlease review [mono's installation guide](http://www.mono-project.com/download/#download-lin) if you are using a different flavor of linux.\n\n## How to debug\n[How to debug mdoc](./Documentation/how-to-debug/how-to-debug-mdoc.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmono%2Fapi-doc-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmono%2Fapi-doc-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmono%2Fapi-doc-tools/lists"}