---------------------------------------------------------------------------------------------------------------------------------------------------------------------

	DocFx is made to generate online API and manuals. It uses a bunch of files which defines how the doc is organised and generate a site_ folder containing all the needed           files to generate the site; Here is how to install and use it in order to generate an API and manual for unity package.

	---------------------------------------------------------------------------------- Setting --------------------------------------------------------------------------
	---------------------------------------------------------------------------------------------------------------------------------------------------------------------


1. Open the windows powershell

2. Install chocolatey:
   Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

3. Install docfx: 
   choco install docfx -y

4. Create a sample project: 
   docfx init -q (This command generates a default project named docfx_project)

5. Build the web site of the sample project: 
   docfx docfx_project\docfx.json --serve

6. Create a Class Library (needs visual studio 2022 or later):
   https://docs.microsoft.com/en-us/dotnet/core/tutorials/library-with-visual-studio?pivots=dotnet-6-0

7. Right click on the project (of the created class library) and select Manage NuGet Package

8. Search and install the docfx.console NuGet package. It adds itself to the build targets and adds the docfx.json configuration file along with other files.

9. Build (Ctrl+F5) -> a site_ folder is created in your project build folder (windows/system32)

10. Download/clone the DocFxForUnity github repository : https://github.com/NormandErwan/DocFxForUnity.git

11. Copy the "document" folder from the repository into your unity project

12. Edit Documentation/docfx.json (keep the other lines as it is ) : 

  {
    "build": {
      "globalMetadata": // Edit your documentation website info, see: https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#322-reserved-metadata
      {
        "_appTitle": "Example Unity documentation",
        "_appFooter": "Example Unity documentation",
        "_enableSearch": true
      },
      "sitemap":
      {
        "baseUrl": "https://normanderwan.github.io/DocFxForUnity" // The URL of your documentation website
      }
  }

13. Edit the Documentation/filterConfig.yml to set the samespace we want to generate the documentation, for more details : https://dotnet.github.io/docfx/tutorial/howto_filter_out_unwanted_apis_attributes.html:

	apiRules:
	- include: # The namespaces to generate
    	uidRegex: ^Your\.Namespace1
    	type: Namespace
	- include:
    	uidRegex: ^Your\.Namespace2
    	type: Namespace
	- exclude:
    	uidRegex: .* # Every other namespaces are ignored
    	type: Namespace
	

	------------------------------------------------------------------------------------ Using ---------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------------------------------------------


1. See https://docs.microsoft.com/en-us/dotnet/csharp/codedoc to check how to document classes and methods of the namespaces.

2. Write a markDown file (.md) for each page in document/manual. A markdown file allows to write easily webpage for our manual by uing some markers:

	* text * or _text_ -> ITALLIC
   	** text ** -> BOLD
	# -> HEADER/TITLE 1
	## -> HEADER/TITLE 2
	### -> HEADER/TITLE 3
	#### -> HEADER/TITLE 4
	###### -> HEADER/TITLE 5
	####### -> HEADER/TITLE 6
	[linkText](www.site.com) -> create a link to www.site.com accessible by clicking on linkText
	![linkText](myImageUrl) -> create a link to the image just like for the website links but is visible from the manual if starts with !
	> Important note (BlockQuote), this make the text bigger (great for NB)

3. List the created manual page (markdown files) in the Documentation/manual/toc.yml file, E.G: 

                     ...

	- name: MadTrixToolkit philosophy
 	 href: MadtrixToolkit_philosophy.md
	- name: MadtrixToolkit Basics
 	 href: MadtrixToolkit_basics.md

		     ...

4. OPTIONNAL : Document the Namespaces. For each namespaces add a Assets/Scripts/Your/Namespace1/Your.Namespace1.md file:

	---
	uid: Your.Namespace1
	summary: Description of the Your.Namespace1 namespace.
	---

5. To generate the documentation launch the powershell from the unity project folder (type powerhsell in the address bar showing the folder path)
   and run : 

	cp README.md Documentation/index.md
	docfx Documentation/docfx.json --serve

   This will create a "site_" folder and the generated website will be visible at http://localhost:8080
   
   
   ------------------------------------------------------------ notes -----------------------------------------------------------------------
   
   If you copy the madtrix-tools project to reuse it and generate the documentation, you'll need to delete the existing "site_" folder.