Docs gen (#27)

* generate readme

* add command names

* fix build: not update if help generating

* remove dots at end of help line

* fix

* add module.yaml doc

* fix space

* fix space

* fix

* del .orig

Author: kunga

Cement.Net/CementEntry.csproj

@@ -114,6 +114,7 @@
     </PropertyGroup>
     <Message Text="MERGING: @(MergeAssemblies->'%(Filename)') into $(OutputAssembly)" Importance="High" />
     <Exec Command="$(Merger) /out:&quot;$(OutputAssembly)&quot; @(MergeAssemblies->'&quot;%(FullPath)&quot;', ' ')" />
+    <Exec Command="$(OutputAssembly) help --gen $(SolutionDir)\README.md" />
   </Target>
   <Target Name="CopyExe" DependsOnTargets="AfterBuild">
   	<Exec Command="rmdir /S /Q %25userprofile%25\bin\dotnet" />

Cement.Net/Program.cs

@@ -17,7 +17,8 @@ private static int Main(string[] args)
             ConsoleWriter.ResetProgress();
 
             var command = args[0];
-            if (command != "complete" && command != "check-pre-commit")
+            if (command != "complete" && command != "check-pre-commit"
+                && (command != "help" || !args.Contains("--gen")))
                 SelfUpdate.UpdateIfOld();
 
             return exitCode == 0 ? 0 : 13;

Commands/Commands.csproj

@@ -68,6 +68,7 @@
   <ItemGroup>
     <Compile Include="AnalyzerAdd.cs" />
     <Compile Include="AnalyzerCommand.cs" />
+    <Compile Include="ReadmeGenerator.cs" />
     <Compile Include="RefAdd.cs" />
     <Compile Include="Build.cs" />
     <Compile Include="BuildDeps.cs" />

Commands/Help.cs

@@ -1,11 +1,20 @@
-using Common;
+using System;
+using System.IO;
+using System.Linq;
+using Common;
 
 namespace Commands
 {
     public class Help : ICommand
     {
         public int Run(string[] args)
         {
+            if (args.Contains("--gen"))
+            {
+                GenerateReadme(args[2]);
+                return 0;
+            }
+
             if (args.Length == 1)
             {
                 CommandsList.Print();
@@ -33,6 +42,15 @@ public int Run(string[] args)
             return -1;
         }
 
+        private static void GenerateReadme(string file)
+        {
+            var text = File.ReadAllText(file);
+            var index = text.IndexOf("# Commands", StringComparison.Ordinal)
+                        + "# Commands".Length;
+            text = text.Substring(0, index) + ReadmeGenerator.Generate();
+            File.WriteAllText(file, text);
+        }
+
         private static void PrintHelpFooter()
         {
             ConsoleWriter.WriteLine("Cement. 2017.");

Commands/ReadmeGenerator.cs

@@ -0,0 +1,49 @@
+namespace Commands
+{
+    public static class ReadmeGenerator
+    {
+        public static string Generate()
+        {
+            var commands = CommandsList.Commands;
+
+            return $@"
+### cm help
+{commands["help"].HelpMessage}
+
+### cm self-update
+{commands["self-update"].HelpMessage}
+### cm --version
+{commands["--version"].HelpMessage}
+
+### cm init
+{commands["init"].HelpMessage}
+### cm get
+{commands["get"].HelpMessage}
+### cm update-deps
+{commands["update-deps"].HelpMessage}
+### cm update
+{commands["update"].HelpMessage}
+
+### cm build-deps
+{commands["build-deps"].HelpMessage}
+### cm build
+{commands["build"].HelpMessage}
+
+### cm ls
+{commands["ls"].HelpMessage}
+### cm module
+{commands["module"].HelpMessage}
+### cm ref
+{commands["ref"].HelpMessage}
+### cm show-configs
+{commands["show-configs"].HelpMessage}
+### cm check-deps
+{commands["check-deps"].HelpMessage}
+### cm show-deps
+{commands["show-deps"].HelpMessage}
+
+### cm status
+{commands["status"].HelpMessage}";
+        }
+    }
+}

Commands/Status.cs

@@ -63,13 +63,13 @@ private void PrintStatus(GitRepository repo)
         }
 
         public string HelpMessage => @"
-    Prints status of modifed git repos in the cement tracked dir.
-    It checks repo for push/pull and local state.
+    Prints status of modifed git repos in the cement tracked dir
+    It checks repo for push/pull and local state
 
     Usage:
         cm status
 
-    Runs anywhere in the cement tracked tree.
+    Runs anywhere in the cement tracked tree
 ";
 
         public bool IsHiddenCommand => false;

Commands/Update.cs

@@ -62,8 +62,8 @@ cm update [-f/-r/-p] [-v] [treeish]
 
         -v/--verbose                show commit info for deps
 
-    This command runs 'update' ('git pull origin treeish') command for module.
-    If treeish isn't specified, cement uses current.
+    This command runs 'update' ('git pull origin treeish') command for module
+    If treeish isn't specified, cement uses current
 ";
     }
 }

README-module.yaml.md

@@ -0,0 +1,157 @@
+# module.yaml
+Информация о модуле содержится в файле `module.yaml`.
+
+Каждый модуль может состоять из одной либо нескольких конфигураций (например конфигурация клиента, конфигурация с серверной частью, и конфигурация включающая тесты).
+
+Каждая конфигурация может включать в себя следующие секции:
+
+- deps
+- build
+- install/artifacts
+
+Конфигурации можно наследовать, что бы избежать дублирования информации о зависимостях.
+
+В модуле должна присутствовать конфигурация `full-build`, которая должна по возможности включать в себя остальные. Она будет использоваться при выполнении команд `cm get` и `cm build`.
+
+Необязательная конфигурация `default` является родителем для всех остальных.
+
+Пример:
+
+	# секция описания конфигурации client
+	client: 
+	  # список зависимостей конфигурации client
+	  # зависимость указывается в следующем виде: <moduleName>[@branchName][/configName]
+	  # kanso - ссылка на модуль kanso. 
+	  # kanso/client - ссылка на kanso в конфигурации client. 
+	  # kanso@develop/client - kanso из ветки develop в конфигурации client
+	  deps: 
+	    - core
+	    - log4net
+	    - nunit
+	    - logging
+	    - http
+	    - http.rp
+	    - topology
+	  
+	  # информация о построении данного модуля в данной конфигурации
+	  build:
+	    # build solution Kontur.Drive.sln in Client configuration
+	    target: Kontur.Drive.sln
+	    configuration: Client
+
+	  # Информация о том, что является результатом билда данной конфигурации
+	  install:
+	    - bin/Kontur.Drive.Client.dll
+	    - bin/Kontur.Drive.ServiceModel.dll
+	    - module logging                      # Для работы Kontur.Drive.Client.dll нужна ссылка на результаты билда модуля logging
+	    - nuget Newtonsoft.Json/6.0.8         # Либо нужена ссылка на nuget пакет
+	  
+	# Конфигурация sdk "расширяет" конфигурацию client (> client) и является конфигурацией по умолчанию (*default) (используется при добавлении ссылки на данный модуль)
+	sdk > client *default:
+	  # Для избежания дублирования списков зависимостей, deps от client наследуются сюда и их не нужно повторно прописывать
+	  deps:
+	    - auth
+	    - libfront
+	    - zebra
+	    - kanso
+	    - upload-service
+	    - access-control
+	    - zebra-utils
+	    - config
+	    - zookeeper
+	  
+	  # Секция build НЕ наследуется
+	  build:
+	    target: Kontur.Drive.sln
+	    configuration: Sdk
+	  
+	  # Секция install наследуется, т.е. необходимо дописать лишь недостающие бинари
+	  install:
+	    - Kontur.Drive.TestHost/bin/Release/Kontur.Drive.TestHost.exe
+	    - Kontur.Drive.TestHost/bin/Release/ServiceStack.Interfaces.dll
+	  
+	  
+	# Конфигурация full-build расширяет client и sdk
+	full-build > client, sdk:
+	  deps:
+	    # Так указывается diff на deps (в конфигурации full-build используется kanso/full-build. Сначала "удаляем" kanso из зависимостей, потом добавляем kanso/full-build)
+	    - -kanso
+	    - kanso/full-build
+	 
+	  build:
+	    target: Kontur.Drive.sln
+	    configuration: Release
+
+
+# build section
+
+#### Для модуля который не надо строить:
+
+	build:
+	  target: None
+	  configuration: None
+
+#### Если нужно указать дополнительные параметры:
+	
+	build:                                             
+	  target: Solution.sln                              # Указание цели построения
+	  tool:                                        
+	    name: msbuild                                   # Инструмент для сборки. msbuild - для MSBuild.exe на Windows и xbuild на *nix.
+	    version: "14.0"                                 # Версия msbuild, по умолчанию - последняя
+	                                                    # set VS150COMNTOOLS=D:\Program Files\Microsoft Visual Studio\2017\Professional\Common7\Tools\
+	                                                    # Обязательно в кавычках
+	  configuration: Release                            # Конфигурация солюшена
+	  parameters: "/p:WarningLevel=0"                   # Здесь можно указать свои параметры. Параметры по умолчанию не используются. Кавычки в параметрах экранируются символом '\'.
+	                                                    # Параметры по умолчанию для msbuild:
+	                                                    # /t:Rebuild /nodeReuse:false /maxcpucount /v:m /p:WarningLevel=0
+	                                                    # /p:VisualStudioVersion=14.0 (если явно указана)
+
+
+#### Если в модуле несколько солюшенов
+	
+	build:
+	  - name: a.release                                # Нужно назвать каждую часть
+	    target: a.sln
+	    configuration: release
+	  - name: b.debug
+	    target: b.sln
+	    configuration: debug
+
+#### Build with custom script:
+
+build.xproj:
+
+	<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+	    <Target Name="Rebuild">
+	        <Exec Command="ping google.com > 1.txt" />
+	    </Target>
+	</Project>
+
+module.yaml:
+
+	full-build:
+	  deps:
+	  build:
+	    target: build.xproj
+	    configuration: Release
+
+# Git hooks
+	
+	default:                                        # Описываем в конфигурации default
+	  hooks:
+	    - myhooks/pre-push                          # Путь до хука в репозитории
+	                                                # будет скопирован в <module_name>/.git/hooks
+	    - pre-commit.cement                         # Встроенный в цемент pre-commit хук, который проверит, что файлы содержащие не ASCII символы имеют кодировку UTF-8 with BOM
+	                                                # не может быть более 1 хука с одинаковым именем
+	  
+	full-build *default:                            # Остальные конфигурации модуля
+
+
+Если в текущей ветке есть хук, то при переключении на другую ветку он не удалится.
+Если вы хотите использовать ваш хук с pre-commit.cement, просто добавьте его вызов в свой хук:
+
+	.git/hooks/pre-commit.cement
+	if [ $? -ne 0 ]; then
+	  exit 1
+	fi
+