You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: websites/site/contributing/documentation.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,12 +18,12 @@ To submit changes for the website, create a Pull Request to the [Lucene Git repo
18
18
19
19
### Build script
20
20
21
-
To build the website and run it on your machine, run the powershell script: `/websites/site/site.ps1`. You don't have to pass any parameters in and it will build the site and host it at [http://localhost:8080](http://localhost:8080).
21
+
To build the website and run it on your machine, run the Powershell script: `/websites/site/site.ps1`. You don't have to pass any parameters in and it will build the site and host it at [http://localhost:8081](http://localhost:8081).
22
22
23
23
The script has 2 optional parameters:
24
24
25
25
-`-ServeDocs`_(default is 1)_ The value of `1` means it will build the docs and host the site, if `0` is specified, it will build the static site to be hosted elsewhere.
26
-
-`-Clean`_(default is 0)_ The value of `1` means that it will clear all caches and tool files before it builds again. This is handy if a new version of docfx is available or if there's odd things occuring with the incremental build.
26
+
-`-Clean`_(default is 0)_ The value of `1` means that it will clear all caches and tool files before it builds again. This is handy if a new version of docfx is available or if there's odd things occurring with the incremental build.
27
27
28
28
### File/folder structure
29
29
@@ -42,21 +42,21 @@ The file/folder structure is within `/websites/site`:
42
42
43
43
- The website is deployed via git
44
44
- Checkout the Git repo that hosts the documentation: https://github.com/apache/lucenenet-site/tree/asf-site_(ensure you have `asf-site` branch checked out, not `master`)_
45
-
- Copy the build output of the website to the root. The build output will be all of the files in the `/websites/site/_site` in your main lucene.net checked out Git repository.
45
+
- Copy the build output of the website to the root. The build output will be all of the files in the `/websites/site/_site` in your main Lucene.NET checked out Git repository.
46
46
- Commit and push these changes
47
47
- The new version of the website will be live. If the amount of new files committed is large, the new files may take some time to become live.
48
48
49
49
## API Docs
50
50
51
51
### Build script
52
52
53
-
To build the api docs and run it on your machine, run the powershell script: `/websites/apidocs/docs.ps1`. You don't have to pass any parameters in and it will build the site and host it at [http://localhost:8080](http://localhost:8080).
53
+
To build the api docs and run it on your machine, run the Powershell script: `/websites/apidocs/docs.ps1`. You don't have to pass any parameters in and it will build the site and host it at [http://localhost:8080](http://localhost:8080).
54
54
55
55
The script has 3 parameters:
56
56
57
57
-`-LuceneNetVersion`_(mandatory)_ This is the Lucene.Net version including pre-release information that is being built. For example: `4.8.0-beta00008`. _(This value will correspond to the folder and branch name where the docs get hosted, see below)_
58
58
-`-ServeDocs`_(default is 1)_ The value of `1` means it will build the docs and host the site, if `0` is specified, it will build the static site to be hosted elsewhere.
59
-
-`-Clean`_(default is 0)_ The value of `1` means that it will clear all caches and tool files before it builds again. This is handy if a new version of docfx is available or if there's odd things occuring with the incremental build.
59
+
-`-Clean`_(default is 0)_ The value of `1` means that it will clear all caches and tool files before it builds again. This is handy if a new version of docfx is available or if there's odd things occurring with the incremental build.
60
60
61
61
### File/folder structure
62
62
@@ -72,13 +72,13 @@ The file/folder structure is within `/websites/apidocs`:
72
72
73
73
### Process overview
74
74
75
-
The documentation generation is a complex process because it needs to convert the Java Lucene project's documentation into a usable format to produce the output Lucene.Net's documentation.
75
+
The documentation generation is a complex process because it needs to convert the Java Lucene project's documentation into a usable format to produce the output Lucene.NET's documentation.
76
76
77
77
The process overview is:
78
78
79
-
- Use the `JavaDocToMarkdownConverter` project within the `DocumentationTools.sln` solution to run the conversion of the Java Lucene projects docs into a useable format for DocFx. This tool takes uses a release tag output of the Java Lucene project as it's source to convert against the Lucene.Net's source.
79
+
- Use the `JavaDocToMarkdownConverter` project within the `DocumentationTools.sln` solution to run the conversion of the Java Lucene projects docs into a useable format for DocFx. This tool takes uses a release tag output of the Java Lucene project as it's source to convert against the Lucene.NET's source.
80
80
- Run the documentation build script to produce the documentation site
81
-
- Publish the output to the [`lucenenet-site`](https://github.com/apache/lucenenet-site) repository into a correpsonding named version directory
81
+
- Publish the output to the [`lucenenet-site`](https://github.com/apache/lucenenet-site) repository into a corresponding named version directory
82
82
83
83
We don't want to manually change the converted resulting markdown files (`.md`) because they would get overwritten again when the conversion process is re-executed. Therefore to fix any formatting issues or customized output of the project docs, these customizations/fixes/tweaks are built directly into the conversion process itself in the `JavaDocToMarkdownConverter.csproj` project.
84
84
@@ -101,12 +101,12 @@ We don't want to manually change the converted resulting markdown files (`.md`)
101
101
102
102
- Checkout the Git repo that hosts the documentation: https://github.com/apache/lucenenet-site/tree/asf-site_(ensure you have `asf-site` branch checked out, not `master`)_
103
103
- Create a new folder in this repo: `/docs/[Version]`, for example: `/docs/4.8.0-beta00008`
104
-
- Copy the build output of the documentation site to this new folder. The build output will be all of the files in the `/websites/apidocs/_site` in your main lucene.net checked out Git repository.
104
+
- Copy the build output of the documentation site to this new folder. The build output will be all of the files in the `/websites/apidocs/_site` in your main Lucene.NET checked out Git repository.
105
105
- Commit and push these changes
106
106
- The new version documentation will be live. Due to the amount of new files committed, the new files may take up to 60 minutes to become live.
107
107
- Next the website needs updating which is a manual process currently:
108
108
- In the `/websites/site/download` folder there should be a document per release. It's normally fine to copy the document of the latest release for the same major version. For a new major version some modifications may be needed.
109
-
- Ensure the correct version number is listed in the header and the nuget download snippet.
109
+
- Ensure the correct version number is listed in the header and the NuGet download snippet.
110
110
- Update the `Status` and `Released` heading information.
111
111
- Ensure the download links are correct.
112
112
- Update the `/websites/site/download/toc.yml` and `/websites/site/download/download.md` files to include a reference to the new page which should maintain descending version order.
0 commit comments