Giter VIP home page Giter VIP logo

vaclavelias / stride-docs-next Goto Github PK

View Code? Open in Web Editor NEW
0.0 4.0 3.0 2.11 MB

Stride Docs Repository: Source code for generating comprehensive Stride documentation using DocFX, featuring Manuals, Tutorials, Release Notes, and API Docs to help users master the Stride game engine with ease and clarity.

License: MIT License

C# 20.78% Batchfile 0.52% CSS 2.37% HTML 5.35% PowerShell 48.51% JavaScript 22.46%

stride-docs-next's Introduction

Stride Docs Development

Welcome to the Stride Docs repository. This repository contains all the source files for the Stride documentation http://doc.stride3d.net/.

🚀 Getting Started

All the information you need to get started with Stride Docs development can be found in the 📚 Stride Docs Wiki.

🤝 Contributing

Use Discord for questions and general discussions. Use Issues to report bugs and proposing features.

We welcome code contributions through pull requests. Issues tagged as help-wanted are good candidates for starting to contribute code.

Branch and Release

The master branch is the default branch for pull requests and most other development activities.

Releases are based on a stable master branch. Use of Conventional Commit is encouraged.

Stride Docs website is not released under a regular cadence; new updates arrive when maintainers fix issues or see enough changes that warrant a new releases.

Staging

The staging website allows us to test new features and significant changes before their official release.

The staging website is available at https://stride-docs-staging.azurewebsites.net/

🗺️ Roadmap

Our Wiki Roadmap communicates upcoming changes to the Stride Docs.

🌐 .NET Foundation

This project is supported by the .NET Foundation.

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the .NET Foundation Code of Conduct.

🛡️License

This project is licensed under the MIT License.

Post-Release Features

  • Dark Theme by Default

Past Content - ToDo: Review

Anyone is welcome to contribute! Before you start, please take the time to read the guidelines.

You can find basic information about editing the documentation in Getting Started dedicated page.

Don't forget to change $version in deploy.ps1 when branching before first deployment.

Manage multiple Stride versions

Each Stride minor version (i.e. 4.0, 4.1, etc.) should have its own branch, named in the fashion master-<version>. The only exception is latest version, which should be master.

stride-docs-next's People

Contributors

ixllegacyixl avatar vaclavelias avatar

Watchers

 avatar  avatar  avatar  avatar

stride-docs-next's Issues

Boolean expression should be questions and strong typed

Like in C# boolean evaluations should be questions.
Also be as concise about types as possible

    [bool]$isENLanguage = $userInput -ieq "en"
    [bool]$isAllLanguages = $userInput -ieq "all"
    [bool]$shouldRunLocalWebsite = $userInput -ieq "r"
    [bool]$isCanceled = $userInput -ieq "c"

the ieq means "ignore case during equal comparison"
e.g.: "r" -ieq "R" would be true

the benefit of stronly typing the bool here is, i dont need any clue about the equasion on the right, i know it will be a boolean to 100%
the benefit of naming booleans as questions is visible when you put them into if statements

if ($isCanceled)
{
   # ...
}

now the if became a proper english sentence and is good readable

Foreach loop with index is confusing.

you have a foreach loop which iterates over all elements and counts up on each element.
This should be only a normal for loop.
A normal for loop should be prefered when using an index for the elements.
your code

    $processedCount = 0

    foreach ($htmlFile in $htmlFiles) {

and it should be

for ($i = 0; $i -lt $htmlFiles.Count; $i++) {
    $htmlFile = $htmlFiles[$i]
....
### Delete this: $processedCount++
...
Write-Progress -Activity "Processing files" -Status "$i of $($htmlFiles.Count) processed" -PercentComplete (($i / $htmlFiles.Count) * 100)
}

Update sitemap.xml

The post processing needs to be run on this file to fix the urls

From
<loc>https://doc.stride3d.net/api/Stride.Animations.AnimationBlender.Channel.html</loc>

To
<loc>https://doc.stride3d.net/latest/en/api/Stride.Animations.AnimationBlender.Channel.html</loc>

Inconsistent Function Naming

Powershell follows the Standard for function names like the following

[VERB]-[NOUN]
[VERB]-[NOUN][NOUN]
[VERB]-[NOUN][NOUN][NOUN][NOUN]

having 3 nouns is uncommon but also acceptable and often used.
There is also the Powershell command Get-Verb to see the "standard verbs" that should be used if possible.
For instance Run is not a common verb, Start is better.
But for some Situations like "Ask" there is no Verb, so its fine. In that case a Company would extend the Verbs in Get-Verb
So Get-Verb is more a "Guideline" than a rule ( i dont follow it either .. i try to use them as best as possible ).

Start-LogTranscript this is a correct Function Name
GetUserInput this is a wrong function name it should be Get-UserInput
RunLocalWebsite this is also a wrong function name it should be Start-LocalWebsite as Run is Uncommon

Remove Remove-BuildLogFile and Start-LogTranscript

Remove-BuildLogFile gets only called one time and immediate afterwards the function Start-LogTranscript.
A starting Transcript will anyway override the content of an existing file.

so for example the .\build.log allready exists then it will get empty and the new transcript will write its content into it.
So the Function doesnt do anything in the end.

It can be removed as its unnecessary.

For the Start-LogTranscript , too many functions are harmful as you will have to jump alot in your Editor and such one liners should be just in the code where the former method gets called
the current code

Remove-BuildLogFile

Start-LogTranscript

Should be rewritten to that, if you included the LogPath in the Settings.

Start-Transcript $Settings.LogPath

If you dont want to include the Logpath in the settings it should be like that

Start-Transcript ".\build.log"

The Methods Remove-BuildLogFile and Start-LogTranscript should be deleted as they cause more confusion.
Powershell is not built like c# where you want to code into the future and prepare for alterations.

Powershell is more designed for "write once and be able to understand it when you read it in 5 years"

Loop until valid answer is given

something like

$validOptions = @('all', 'r', 'c')
while($true)
{
    $input = Read-Host -Prompt "Your choice"
    if($validOptions -contains $input)
    {
        return $input.ToLower()
    }
}
Write-Error "No valid Choice was given." 

Forgotten /manual

Write-Host -ForegroundColor Yellow "Warning: $($SelectedLanguage.language)/manual not found."

and
$posts = Get-ChildItem $langFolder/manual/*.md -Recurse -Force

should use the new $Settings.ManualFolderName
else it would result in a bug when the folder name gets changed

Missing Help Documentation

Its the most important documentation of a powershell script, so all people can get an idea how it should be used.
Every Powershell Script should start with a help documentation to get a sense about what is going on in this script.
Also it Embeds the Script into Get-Help

Its also possible to add that specific help document to each function.. but no Powershell IDE can resolve the comments and it just results in a 1k line script.. so i would only add it for the entry of the script.

Docs about how to create a Help Documentation:
https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.3

For Instance it could look like that

<#
.SYNOPSIS
    One liner about what it does for example: Builds all Documentation Sites for all languages in the languages.json
.DESCRIPTION
    Longer in Depth explanation of how the script works for example:
    Takes the languages.json in the current directory and gets the languages from it
    There is only a 
.NOTES
    Information or caveats about the function e.g. 'This script is compatible with github actions'
.LINK
    Links to your sites where this is connected to and giving additional resources for example:
    https://github.com/VaclavElias/stride-website-next
    https://github.com/VaclavElias/stride-docs-next/blob/main/languages.json
.PARAMETER BuildAll
   What is this parameter doing? you can declare foreach parameter such a block
.EXAMPLE
    BuildDocs.ps1 -BuildAll
    Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines
.EXAMPLE
    BuildDocs.ps1
    A second example
#>
param (
    [switch]$BuildAll
)
.....

exit is considered harm ful

The problem about exit is that you cant loop over it.
Powershell also focus on other people to make it usable.

for example i want to loop over your script and want to have a test scenario or something
like so

foreach($x in $myCollection) {
    .\Build.ps1
}

then the loop CANT continue when i cancel a script generation.
And its even worse than that, it will also kill my script! as it exits the entire powershell.
So unintentional damage could be caused with this.

As same as the Start-Transcript i would clean it up from your current code

function HandleCancel {
    Write-Host -ForegroundColor Red "Operation canceled by user."
    Stop-Transcript
    Read-Host -Prompt "Press ENTER key to exit..."
    exit
}

....

if ($cancel)
{
    HandleCancel
}

to that

if ($isCanceled) # or $cancel if you dont want to use the Question naming style
{
    Write-Host -ForegroundColor Red "Operation canceled by user."
    Stop-Transcript
    Read-Host -Prompt "Press ENTER key to exit..."
    return
}

inconsitency of keywords

the keyword style of the script varys

for example If and if is used or Foreach

for the ifs both are valid and used.
But the foreach should be ForEach or foreach

pascal case and snake case of keywords shouldnt be mixed, one style should be chosen, the most common is all snake case

Convert Constants to a single Settings Object

Each possible Configuration or Constants should be grouped up into a single Custom Object.
For Example

# Define constants
$TmpDir = "_tmp"
$SiteDir = "_site"

Should be this

$Settings = [PSCustomObject] @{
  TempDir = "_tmp"
  SiteDir = "_site"
}

Accessing the Variables would be like this

$Settings.TempDir

Windows uses as Standard the "temp" wording, linux uses the wording "tmp"

i would either drag other settings into the Settings variable or make a second one for "Configuration" e.g.
the String 'languages.json' is only used one time but plays a significant role in the usage of the script.
it would be better to add it to the Settings so another user can use his custom location of his settings.json
The user can then alter the settings without knowing how the file is actually treated, also i would change it to a relative path to make the usage more precise e.g.

$Settings = [PSCustomObject] @{
    TmpDir = "_tmp"
    SiteDir = "_site"
    LanguageFile =".\languages.json"
}

And the usage would look like
return Get-Content $Settings.LanguageFile -Encoding UTF8 | ConvertFrom-Json
now there is no "magic string" anymore in this line.
I do not count prompts or messages as magic strings, but for parameters or values that play a significant role, its better this way

Also i would include the "build.log" string into the settings e.g.

$Settings = [PSCustomObject] @{
    TmpDir = "_tmp"
    SiteDir = "_site"
    LanguageFile =".\languages.json"
    LogPath = ".\build.log"
}
and usage would be 
`Start-Transcript -Path $Settings.LogPath`

Add Verbosity

For the Transcript it helps to track back what happened if more statements give results.
Here it would be appropriate to add verbosity

        Remove-Item en/api/*yml -recurse
        Remove-Item en/api/.manifest

should be

        Remove-Item en/api/*yml -recurse -Verbose
        Remove-Item en/api/.manifest -Verbose

Pascal Case for Parameters

The standard of Powershell is that a function has its Parameters in PascalCase.
if you write in your powershell Get-Help - and move the cursor after the minus symbol and press ctrl + spacebar you will see that all possible parameters are in pascal case.

function BuildNonEnglishDoc {
    param (
        $selectedLanguage
    )

this should be like that

function BuildNonEnglishDoc {
    param (
        $SelectedLanguage
    )

same for

    param (
        [array]$Languages
    )

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.