nodatime / nodatime.org

Source code for the nodatime.org web site

Noda Time is an alternative date and time API for .NET. It helps you to think about your data more clearly, and express operations on that data more precisely.

• Project web site - for documentation, installation, downloads etc
• Group/mailing list - for discussion of potential features
• Project source and issue site
• Stack Overflow tag - for specific "How do I do X?" questions

Contributing

We appreciate your interest in contributing to Noda Time. See the contribution guidelines for more details.

nodatime.org's Issues

Bagpuss build is broken

Looks like we aren't deploying new builds

Is it finally time to move to a Cloud docs build?

Reinstate CheckMembers in DocfxAnnotationGenerator

Prefer absolute links in generated docfx output

Docfx seems to enjoy using relative links for CSS, favicon(?!), and JS, among others. This is fine, except that we have some evidence that at least some subset of User-Agents is choking on this, and for e.g. http://nodatime.org/2.0.x/api/NodaTime.html is resolving "../../styles/docfx.css" to http://nodatime.org/2.0.x/styles/docfx.css (which is 404, and wrong).

Mostly this should be as simple as removing {_rel} from some of the URLs (and creating partials where needed).

(But note that ../toc.html as used in the docfx:navrel link is correct: http://nodatime.org/2.0.x/api/toc.html and http://nodatime.org/2.0.x/toc.html are different documents.)

While we're here, we can also fix a few other minor niggles:

• main.css and main.js are empty. We don't need to load them.
• The clock link in the navbar should go to /, not ../../index.html (which just earns it an extra 302).
• Likewise the Home and User guide links in the navbar (read from the higher-up toc.html) should go to / and userguide/, rather than ../index.html and userguide/index (the latter messes up Analytics a bit).

Text equivalent of standard patterns drops the final apostrophe

On the ZonedDateTime patterns page, the text equivalent of the G pattern is listed as: uuuu'-'MM'-'dd'T'HH':'mm':'ss z '('o<g>'), while the text equivalent of F is listed as uuuu'-'MM'-'dd'T'HH':'mm':'ss;FFFFFFFFF z '('o<g>').

Both of these are missing a trailing ', and should be:

Standard pattern	Text equivalent
'G'	uuuu'-'MM'-'dd'T'HH':'mm':'ss z '('o<g>')'
F	uuuu'-'MM'-'dd'T'HH':'mm':'ss;FFFFFFFFF z '('o<g>')'

Stop using inheritdoc or fix it to work

docfx gives us hundreds of warnings like this:

Could not resolve base documentation for 'NodaTime.Serialization.JsonNet.DelegatingConverterBase.WriteJson(Newtonsoft.Json.JsonWriter,System.Object,Newtonsoft.Json.JsonSerializer)'

This is due to the use of inheritdoc. We should work out what to do about this; it's unlikely to get fixed in docfx 2.x.

Wrong constant in zoneintervaltransition description

https://nodatime.org/developer/tzdb-file-format

The datatype zoneintervaltransition is described as possibly containing

number of minutes is in the range [1048576, Int32.MaxValue]

However, the corresponding constant in nodatime is 2097152.

try.dot.net editors are broken

Looks like the Try .NET API may have changed (or I've messed up somewhere else)

https://nodatime.org/3.0.x/userguide/recipes comes up with the sample recipe (after a delay) but the request fails with a 400.

TOC items are out of order

We're just concatenating the tocs - we should merge and sort them instead

Exceptions in logs

We've started getting a lot of KeyNotFound exceptions:

  exception:  "System.Collections.Generic.KeyNotFoundException: The given key 'b2a022ba-6cb0-4c21-8e08-9f78f0b2ea0b' was not present in the dictionary.
   at System.Collections.Generic.Dictionary`2.get_Item(TKey key)
   at lambda_method(Closure , Object , Object[] )
   at Microsoft.Extensions.Internal.ObjectMethodExecutor.Execute(Object target, Object[] parameters)
   at Microsoft.AspNetCore.Mvc.Internal.ActionMethodExecutor.SyncActionResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments)
   at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeActionMethodAsync()
   at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeNextActionFilterAsync()
   at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.Rethrow(ActionExecutedContext context)
   at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
   at Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker.InvokeInnerFilterAsync()
   at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeNextResourceFilter()
   at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Rethrow(ResourceExecutedContext context)
   at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
   at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeFilterPipelineAsync()
   at Microsoft.AspNetCore.Mvc.Internal.ResourceInvoker.InvokeAsync()
   at Microsoft.AspNetCore.Builder.RouterMiddleware.Invoke(HttpContext httpContext)
   at Microsoft.AspNetCore.StaticFiles.StaticFileMiddleware.Invoke(HttpContext context)
   at Microsoft.AspNetCore.StaticFiles.StaticFileMiddleware.Invoke(HttpContext context)
   at Microsoft.AspNetCore.Diagnostics.ExceptionHandlerMiddleware.Invoke(HttpContext context)"   
  log_name:  "Microsoft.AspNetCore.Diagnostics.ExceptionHandlerMiddleware"   
  message:  "An unhandled exception has occurred while executing the request."   

Snippet generator should reformat code after removing asserts

https://github.com/nodatime/nodatime/blob/c9220cd/src/NodaTime.Demo/ZonedDateTimeDemo.cs#L105 has:

Assert.AreEqual("2017-07-20T07:30:00 Europe/Dublin (+01)",
    pattern.Format(Snippet.For(zoned.PlusHours(1))));

And so https://nodatime.org/2.4.x/api/NodaTime.ZonedDateTime.html#NodaTime_ZonedDateTime_PlusHours_System_Int32_ has:

Console.WriteLine(    pattern.Format(zoned.PlusHours(1)));

Obviously it would be nice if the snippetizer reformatted code completely, though perhaps it could just do something simpler to trim leading whitespace?

Snippets are broken yet again

We should potentially revisit the whole thing - this clearly isn't working well...

Fix serialization docs

If we link to the serialization types anywhere in the user guides, it should be to the new home

Migrate to Artifact Registry

Container Registry is deprecated

Move "history" branch

It should really be in nodatime.org

At the same time, we can get rid of the serialization part from it

Consider using DocFX cross-references for Json.NET

See comments in nodatime/nodatime#693 (using our generated xrefmap.yml from an external project).

We should consider using a similar pattern for our dependencies; in particular, Json.NET.

Remove "user guide" from serialization toc

Fix docfx problems

Building the history is now failing:

[20-05-22 07:32:32.022]Warning:ExtractMetadataWorkspace failed with: [Failure] Msbuild failed when processing the file 'C:\users\jon\Test\Projects\nodatime.org\build\history\main\3.0.x\src\NodaTime\NodaTime.csproj' with message: Could not load SDK Resolver. A manifest file exists, but the path to the SDK Resolver DLL file could not be found. Manifest file path 'C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\MSBuild\15.0\Bin\SdkResolvers\Microsoft.Build.NuGetSdkResolver\Microsoft.Build.NuGetSdkResolver.xml'. SDK resolver path: C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\Common7\IDE\CommonExtensions\Microsoft\NuGet\Microsoft.Build.NuGetSdkResolver.dll C:\users\jon\Test\Projects\nodatime.org\build\history\main\3.0.x\src\NodaTime\NodaTime.csproj

Fix vendor JS being missing

Use Travis / AppVeyor

Try.Net examples throw compilation error

I am trying to test the examples on this examples page in the provided test window.

After copying code (by clicking on one of the provided "copy to editor" buttons) and clicking "Run", I see "Running..." in the output display indefinitely. After clicking "Run a second time, I get "CompilationError" in the Output display.

Upgrade to ASP.NET Core 3.1

It looks like there are no longer Docker images for ASP.NET Core 2.2 (which is reasonable, as it's EOL).

We need to work out what's required to upgrade to 3.1, and do so ASAP.

Link from serialization to unstable

When types in serialization refer to the main API, we should make the link work

Examine toc references

Our missing redirect detector found a bunch of referrals for toc.html that I believe are from docfx.

Example:

http://nodatime.org/1.1.x/api/NodaTime.TimeZones.Resolvers.html to /1.1.x/api/toc.html

I believe this is due to this HTML:

<meta property="docfx:navrel" content="../toc.html">
<meta property="docfx:tocrel" content="toc.html">

I'm not sure what the purpose of that is though, or why we get a 404 (going there with a browser is fine).

Update docfx again

It looks like some of the problems around 2.6x.x have been fixed, e.g. it ignoring the command line argument for docfx.json. Maybe there are other fixes too... it's probably worth looking into everything we changed in May.

Fix/Add documentation for 3.0

Now that 3.0 have been released, we need some documentation.

This means at least the following:

• branch src/NodaTime.Web/Markdown/unstable/ to src/NodaTime.Web/Markdown/3.0.x (which will fix https://nodatime.org/userguide/).
• remove all of the unstable/ directory except for src/NodaTime.Web/Markdown/unstable/index.json, which needs an updated parent.
• add the generated API documentation; I think this is done nowadays by updating and then running https://github.com/nodatime/nodatime.org/blob/master/build/buildhistory.sh. (This will fix https://nodatime.org/api/.)
• add information about the new version to https://nodatime.org/versions. (@jskeet already has a draft for this.)
• update/follow https://nodatime.org/developer/release-process as-needed.
• update https://nodatime.org/developer/roadmap as-needed.

Plus any minor updates we run into while doing the above:

• I've just run across a misplaced localdate-patterns.md from 67ee2e2 that should be fixed before we branch the userguide above.
• https://nodatime.org/developer/website has a lot of dead links.

I'm going to take a look at the latter group; @jskeet will do the former.

Design a strategy for documenting serialization packages

As of 2.x, we're not tying our serialization packages (currently just NodaTime.Serialization.JsonNet, but I'm expecting to add NodaTime.Serialization.Protobuf - not sure whether that will start as 1.0 or be 2.0 from the get-go...) to the main NodaTime package versioning. There can be a NodaTime 2.1 without a corresponding NodaTime.Serialization.JsonNet release, or there could be 2.1 and 2.2 of NodaTime.Serialization.JsonNet without a corresponding NodaTime release.

We've currently moved the serialization code into its own repo. That may or may not prove to be a mistake. (Hopefully not...)

So how do we document the serialization projects?

• It probably makes sense to keep "unstable" in the API docs including the latest unreleased code from all packages
• It probably makes sense to keep NodaTime.Serialization.JsonNet in with 2.0.x as they really were released together
• What about for NodaTime 1.1? 1.4? Other serialization package releases?

Namespace docs not being used

We have classes called NamespaceDoc for documentation purposes. Sandcastle used to recognize this; docfx doesn't (yet). There's an issue here for it: dotnet/docfx#952

We should keep track of what docfx is doing and respond appropriately.

Annotate serialization

It would be nice to be able to see what version each member appeared in for serialization

Build in Cloud Run

If we can get this to build and push in Cloud Run (triggered by a change in any repo) it'll be a lot simpler than maintaining bagpuss.

Fix claim of missing members

IXmlSerializable.ReadXml(XmlReader), IXmlSerializable.WriteXml(XmlWriter) and IComparable.CompareTo(Object) are apparently not being reported now.

Investigate SDK version issues in logs

The start of a recent log included:

Copying metadata for previous versions
Building packages and metadata for local code (may not be committed)
Microsoft (R) Build Engine version 16.5.0+d4cbfca49 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

Microsoft (R) Build Engine version 16.5.0+d4cbfca49 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

Microsoft (R) Build Engine version 16.5.0+d4cbfca49 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

Microsoft (R) Build Engine version 16.5.0+d4cbfca49 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

Microsoft (R) Build Engine version 16.5.0+d4cbfca49 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

The specified SDK version '3.1' could not be parsed
The specified SDK version '3.1' could not be parsed
A compatible SDK version for global.json version: [3.1] from [C:\Users\Jon\NodaTime-Web-Builds\92e81ea5_33c8ec4a_3769d850\nodatime\global.json] was not found
The specified SDK version '3.1' could not be parsed
The specified SDK version '3.1' could not be parsed
A compatible SDK version for global.json version: [3.1] from [C:\Users\Jon\NodaTime-Web-Builds\92e81ea5_33c8ec4a_3769d850\nodatime\global.json] was not found
The specified SDK version '3.1' could not be parsed
The specified SDK version '3.1' could not be parsed
A compatible SDK version for global.json version: [3.1] from [C:\Users\Jon\NodaTime-Web-Builds\92e81ea5_33c8ec4a_3769d850\nodatime\global.json] was not found
The specified SDK version '3.1' could not be parsed
The specified SDK version '3.1' could not be parsed
A compatible SDK version for global.json version: [3.1] from [C:\Users\Jon\NodaTime-Web-Builds\92e81ea5_33c8ec4a_3769d850\nodatime\global.json] was not found


Build succeeded.
	0 Warning(s)
	0 Error(s)
A compatible SDK version for global.json version: [2.2.400] from [C:\Users\Jon\NodaTime-Web-Builds\92e81ea5_33c8ec4a_3769d850\nodatime.serialization\global.json] was not found
A compatible SDK version for global.json version: [2.2.400] from [C:\Users\Jon\NodaTime-Web-Builds\92e81ea5_33c8ec4a_3769d850\nodatime.serialization\global.json] was not found
A compatible SDK version for global.json version: [2.2.400] from [C:\Users\Jon\NodaTime-Web-Builds\92e81ea5_33c8ec4a_3769d850\nodatime.serialization\global.json] was not found

That's not encouraging

Fix snippet generator

We get the following warnings:

SnippetFileSyntaxTree.cs(57,24): warning RS1024: Compare symbols correctly [C:\projects\nodatime-org\build\SnippetExtractor\SnippetExtractor.csproj]
SnippetRewriter.cs(85,52): warning RS1024: Compare symbols correctly [C:\projects\nodatime-org\build\SnippetExtractor\SnippetExtractor.csproj]
SnippetRewriter.cs(90,52): warning RS1024: Compare symbols correctly [C:\projects\nodatime-org\build\SnippetExtractor\SnippetExtractor.csproj]
SnippetRewriter.cs(95,52): warning RS1024: Compare symbols correctly [C:\projects\nodatime-org\build\SnippetExtractor\SnippetExtractor.csproj]

Broken link on Installation page

On the Installation page, under "System requirements", there's a link to the .NET Standard versions documentation. This link is broken. I would provide a PR but I'm not quite sure what information that page used to contain!

Fix missing xrefmaps

https://nodatime.org/3.0.x.xrefmap.yml doesn't download - should it?

Search timezones

Can you provide a search bar in this page https://nodatime.org/TimeZones to simplify the search of a specified timezone (at least by name and country) ?

Update to ASP.NET Core 3.0

We should then be able to update Blazor too

API documentation doesn't document nullable reference types

This might be (effectively) a dupe of nodatime/nodatime#1269, but I notice that none of the generated API documentation includes anything about nullable reference types.

Two examples:

• ZonedDateTimePattern.WithResolver() accepts a ZoneLocalMappingResolver?, but the documentation just shows it as ZonedDateTimePattern.WithResolver(ZoneLocalMappingResolver).
• IDateTimeZoneProvider.GetZoneOrNull() returns a DateTimeZone?, but the documentation shows it as DateTimeZone GetZoneOrNull(string id).

Document list of zone IDs

One of the key things listed in the example sitting front and center on the main page of the NodaTime website, is the presence of a hardcoded string for the timezone provider ID. Finding a list of these possible values available online was surprisingly difficult to track down.

There is a GitHub post by user jrolstad here https://gist.github.com/jrolstad/5ca7d78dbfe182d7c1be which provides the code to generate the list and the list's output.

However, given that this is such a key thing to use the NodaTime library, the Zone ID list should be very accessible and findable on the NodaTime website.

Search feature on web site

The nodatime.org web site could really use a Search feature.

Original issue reported on code.google.com by mj1856 on 1 Sep 2013 at 7:34

Exception deserializing xrefmap

Running the build, we get a warning:

Warning:[BuildCore.Build Document]Unable to download xref map file from https://nodatime.org/2.4.x.xrefmap.yml, details: (Line: 13202, Col: 8, Idx: 753941) - (Line: 13202, Col: 49, Idx: 753982): Exception during deserialization

It seems to be basically working, so I'm not sure what's wrong...

Investigate this warning when building history

[20-05-22 07:45:25.340]Warning:ExtractMetadataWorkspace failed with: [Failure] Msbuild failed when processing the file 'C:\users\jon\Test\Projects\nodatime.org\build\history\main\3.0.x\src\NodaTime.Testing\NodaTime.Testing.csproj' with message: C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Current\Bin\Microsoft.Common.CurrentVersion.targets: (1655, 5): Project '..\NodaTime
\NodaTime.csproj' targets 'netstandard2.0'. It cannot be referenced by a project that targets '.NETFramework,Version=v4.5'.

What's trying to do that?

Add redirects where appropriate

http://nodatime.org/1.1.x/api/html/M_NodaTime_CalendarSystem_GetIslamicCalendar.htm gets hits from http://ali-husein.blogspot.com/2015/02/pemrogramman-kalender-bulan.html - let's redirect it.

Upgrade actual web site to .NET 8

Use NodaTime.sln in web build

It can then be deleted from the nodatime repo