Skip to content

Natural Docs 2.3 released: Dark Themes

Latest
Latest
Compare
Choose a tag to compare
@NaturalDocs NaturalDocs released this 12 Sep 03:57
· 43 commits to master since this release
Version_2.3
0315f20

Time for another release. Let's recap what's new for the people who haven't been following the development releases.

Dark Themes

Natural Docs now has dark themes. Rather than just being new styles you can choose for your project, you're able to let the user choose which one they want from the browser. Just click the moon icon next to the search box:

themes_menu_with_auto

The dark theme is what you'd expect, and the black theme has less color and higher contrast. The auto themes will switch between two automatically based on whether your operating system is in light mode or dark mode, so if you have your OS switch between them on a timer you can have the documentation follow it.

Here's a peek at what the dark theme looks like. You can also see it for yourself here.

dark_theme

  • How do I apply this to my project?
    Just download 2.3 and run it on your project.

  • What if I have a custom style?
    All your existing CSS should apply to the light theme with no changes. The dark and black themes will just recolor it.

  • Can I customize the other themes too?
    Yes, just add additional CSS rules with .DarkTheme and .BlackTheme ahead of them. So in addition to styling ".SHComment" you would also style ".DarkTheme .SHComment" and ".BlackTheme .SHComment".

  • Can I disable the other themes?
    If you're not using a custom style, choose Light as the style in Project.txt or on the command line. If you have a custom style based on Style.txt, edit it to inherit from Light instead of Default. If you just use a CSS file as a style, add "#NDThemeSwitcher { display: none !important; }".

  • Can I force it to always use dark?
    If you're not using a custom style, choose Dark as the style in Project.txt or on the command line. If you have a custom style based on Style.txt, edit it to inherit from Dark instead of Default. You can't do it with just a CSS file because those always inherit from Default.

Better macOS Compatibility

The SQLite binaries are now signed and notarized, so you shouldn't have issues with macOS blocking them saying the developer can't be verified. They should just work without you needing to make an exception in the System Preferences. If Natural Docs has ever crashed complaining about libNaturalDocs.Engine.SQLite.Mac64.so this was why.

SystemVerilog

Work on full language support for SystemVerilog continues but is not ready yet, so 2.3 still has basic language support. There's an entry in Languages.txt for it, but this is just a placeholder so you'll probably still need to fill it out a bit more with your own settings to use it. However, the syntax highlighting has been improved. All of SystemVerilog's keywords will highlight correctly as well as complicated numeric literals like 8'b0011_00zz.

Fully-Qualified Title Fix

Probably because I primarily work in C#, which has full language support, and JavaScript, where I only use pseudo-classes, I didn't realize this wasn't working. Suppose you have this:

namespace MyNamespace {

   // Class: MyNamespace::MyClass
   class MyClass {
      ...
      }
   }

You wouldn't get a prototype for MyClass because the declaration doesn't match the full title of MyNamespace::MyClass. This has been fixed, so it only requires the last segment to exist in the prototype now.

Odds and Ends

  • HTML Modernization. Just like SQL before it, SystemVerilog caused a big refactor of the prototype handling code due to how different it can be from other languages. As a result, prototype output has been completely rebuilt using CSS's grid feature. This in turn increases the minimum browser requirements for the documentation, but all the major browsers implemented grid support sometime in 2017, so it's still pretty conservative. It just means no more Internet Explorer and no more pre-Chromium Edge.

  • Better Prototype Formatting. The new prototype code improves formatting for things like C# properties, indexers, and events. Your function and variable prototypes should look almost exactly the same though. There's a few spacing tweaks that may be applied but they're subtle.

  • Maximum Line Length. This is something I've always been ambivalent about doing. I've always liked text going to whatever window size you choose, but on an ultrawide monitor it does get kind of ridiculous. So now there's a maximum line length for readability, but it only affects plain text. If you have a really wide prototype, code block, or image it will still take as much horizontal space as it needs instead of forcing you to scroll.

    If you want to turn it off, make a custom style with this rule:

    .CTopic p,
    .CTopic li p,
    table.CDefinitionList { max-width: none !important }

  • Other minor bug fixes and tweaks.

  • Download MSI for Windows

  • Download Zip file for all platforms

Assets 2