profile
viewpoint
Andreas Deininger deining Germany

deining/EmWiTutorial 1

Embedded Wizard tutorial and sample application: https://deining.github.io/EmWiTutorial/

deining/alpine-ad 0

A rugged, minimal framework for composing JavaScript behavior in your markup.

deining/anatole 0

Anatole is a minimalist two-column hugo theme based on farbox-theme-Anatole.

deining/asciidoctor 0

:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.

deining/asciidoctor-gradle-plugin-ad 0

A Gradle plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.

deining/asciidoctorj-tabbed-code-extension-ad 0

An AsciidoctorJ extension for rendering code on multiple tabs.

deining/aws-sdk-go-v2-ad 0

AWS SDK for the Go programming language V2.

deining/bigfloat 0

Additional operations for the standard library big.Float type

deining/bilberry-hugo-theme 0

Premium theme for the hugo site builder. DEMO:

deining/CLI11 0

CLI11 is a command line parser for C++11 and beyond that provides a rich feature set with a simple and intuitive interface.

PR closed google/docsy

Reviewers
Fix the build for docsy-as-submodule (#858)

This PR resolves #850. Also doing some whitespace cleanup.

+49 -34

1 comment

2 changed files

deining

pr closed time in a few seconds

pull request commentgoogle/docsy

Fix the build for docsy-as-submodule (#858)

#860 covers this too, so I'm closing this PR.

deining

comment created time in a few seconds

push eventdeining/docsy

Andreas Deininger

commit sha 00537ca35660135cf67c0fdab2fd5d027c81b75e

Fix the build for docsy-as-submodule (#858)

view details

push time in 4 minutes

push eventdeining/docsy

Andreas Deininger

commit sha 84d1d2132875e603644cc69afb19a8e799e84951

Fix the build for docsy-as-submodule (#858)

view details

push time in 7 minutes

push eventdeining/docsy

Andreas Deininger

commit sha a4d265bb7b4fbb1a4aa1266794bccb7ca75518f6

Fix the build for docsy-as-submodule (#858)

view details

push time in 28 minutes

PR opened google/docsy

Fix the build for docsy-as-submodule (#858)

This PR resolves #850.

+5 -0

0 comment

1 changed file

pr created time in 31 minutes

PR closed google/docsy

Fix the build for docsy-as-submodule (#858)

I see our commits crossed. I think essentially, they were the same. Prepared a patch for reverting the userguide to git submodules already, stay stuned, it will come in shortly.

+1 -19

2 comments

1 changed file

deining

pr closed time in 31 minutes

pull request commentgoogle/docsy

Fix the build for docsy-as-submodule (#858)

Patrice was faster, thank you!

deining

comment created time in 31 minutes

create barnchdeining/docsy

branch : issue-850

created branch time in 32 minutes

push eventdeining/docsy

Patrice Chalin

commit sha 2a6521461d15453e6cd20a5a6a5b73af2291de37

CI: reintroduce explicit call to npm install (#859)

view details

Patrice Chalin

commit sha 0d033fac5d2f61224a219b6a6f57f6133adc2ff8

Effectively revert #801, removing docsy as a Hugo module (#860)

view details

push time in an hour

PR opened google/docsy

Fix the build for docsy-as-submodule (#858)
+1 -19

0 comment

1 changed file

pr created time in an hour

create barnchdeining/docsy

branch : issue-858

created branch time in an hour

issue openedgoogle/docsy

Userguide: set and display current version, versioning

Browsing the user guide sources, I just realized that the version parameter inside config.toml of the userguide is not set:

119 # The version number for the version of the docs represented in this doc set.
120 # Used in the "version-banner" partial to display a version number for the 
121 # current doc set.
122 version = "0.0"

Since we no do have our first version 0.1.0 in place, I suggest we set this version number when releasing future versions. I think a release checklist would be helpful, one item to be checked should be increment of the version number so that this is not forgotten. Not sure if we want to set x.x.x-dev for all commits between releases. Since we now do have a version number, I would like to see this version number printed in the headline of the docsy userguide. Not sure if we should/want to populate the dropdown with older versions of the userguide, allowing to look at older versions of the user guide. I don't think the current repo structure allows for this easily, but I may be wrong here.

created time in an hour

fork deining/docuapi

Beautiful multilingual API documentation theme for Hugo

https://docuapi.netlify.com/

fork in 2 hours

issue commentgoogle/docsy

Ensure a smooth transition for existing docsy-as-submodule users

Dependencies are declared in config.toml as module, but these modules can be resolved only in module context, not in submodule context (by creating folder structure via my adaption routine, they can be resolved again).

I can make all three dependencies direct dependencies of my site:

my-site -> docsy
my-site -> bootstrap
my-site -> font-awesome

This solves the issue for submodules, and I declare the module imports inside config.toml of my-site only when I really want to use hugo modules. But now docsy theme doesn't know anything about the versions of its dependencies. That's like we removed submodules bootstrap and Font-Awesome from our current repo: a no go.

I have to correct me here: that's not a no go, that's actually the way to go. What I totally overlooked: docsy theme still knows about the versions of its dependencies, they are declared inside go.mod:

module github.com/google/docsy

go 1.17

require (
	github.com/FortAwesome/Font-Awesome v0.0.0-20210804190922-7d3d774145ac // indirect
	github.com/twbs/bootstrap v4.6.1+incompatible // indirect
)

So pulling up docsy subdependencies to the top level is actually the key to resolve #858 and all associated tickets. No multiple config files, no multiple config directories, forget about it. Easy and clean. The only thing that's all but easy is bootstrapping / starting up sites that make use of docsy as hugo module for the very first time. But we can handle this. I'm working on it, give me time until the end of the weekend and we have that resolved, incl. documentation. Good night.

chalin

comment created time in 18 hours

issue commentgoogle/docsy

Fix the build for docsy-as-submodule

Another idea came to my mind: what about reverting #801, then adding a new directory hugo-module, recreating all folders from root level (except for userguide) and then turn this subfolder hugo-module into a module. Inside this folder, I could create my own custom config.tomlwithout getting in conflict with the config.toml at site root. I'm not sure this does work, but it could. Then users that want to use docsy as module have to write inside their site config.toml:

theme = ["github.com/google/docsy/hugo-module"]

This would break builds for users that migrated already. Not sure that we can bring #852 in a form that allows seamless update for migrated installs either.

WDYT of this? Would you prefer this over #852 in it's current form (incl. amendments as discussed).

chalin

comment created time in a day

issue commentgoogle/docsy

Ensure a smooth transition for existing docsy-as-submodule users

Note: given that the configDir name seems to have a "global" scope, it would probably be better to choose a docsy-specific names like docsy-hugo-module and docsy-git-submodule rather than configModule and configTheme.

I see the point, but I'm not fully convinced yet, since this renaming removes the notion that this a a config dir.

What about config-docsy-hugo-module and config-docsy-git-submodule? That's more precise, but having to type hugo serve --configDir config-docsy-git-submodule is a kind of a hassle. I chose short directory names for a reason!

Feedback/opinions are appreciated here!

chalin

comment created time in a day

issue commentgoogle/docsy

Fix the build for docsy-as-submodule

Based on the above comment, I believe that it wasn't @LisaFC's intention to merge #801 and introduce such a serious breaking change: #801 broke the builds of most users.

It wasn't my intention either, and I wasn't aware of the fact that it would break builds. Anyway, that's history now, let's look forwards.

I think finalizing #852 is the way to go, I just presented a further idea how to make it work in the desired way. Due to other private and job-related oblgaions, I couldn't work on this during the week as wanted. I will investigate the opportunities during the weekend and will post my findings shortly.

chalin

comment created time in a day

pull request commentgoogle/docsy

Ensure a smooth transition for existing docsy-as-submodule users #848

Ooh, that's a very interesting approach, though does it mean that if you just run hugo serve nothing will happen?

Yes, in its current form, nothing happens, which will break existing build. Not good, no option at all.

Is there a way to make our current "submodules" behaviour the default as it means it won't break people's continuous deployment (including ours)?

Ther ecertainly is a way: we simply copy config.toml from configTheme the into site root. This will bring back the default submodule functionality to docsy, this is a must since we don't want to break exiszting builds. The question now is: With this file added, are we still allowed to use as hugo module. I have a way in mind, but I'm not sure that it works. I need to test it. Fortunately I do have a playground branch on my own, this wasn't the case in the past. I will come up with the results shortly.

deining

comment created time in a day

issue commentgoogle/docsy

Inconsistent and vague docu on minimum required hugo version

Given the limited development resources that Docsy has, I'd suggest that we officially support only the release of Hugo specified in package.json (which we'll be keeping up to date):

You are addressing the issue of the officially supported version, while I was talking about minimum required version. Both are different concepts, IMHO, in that sense:

  • officially supported version: this is the only supported version, if you use any other version and run into trouble, you are at your own.

  • minimum required version: we know for sure, that docsy breaks with version x.x.x, don't even try it, it's a waste of time.

  • IMHO, we should tell a minimum required version of docsy, at least if we are aware of anys issue inside docsy with versions older than x.x.x Or can we force everyone onto the lastest released version (0.92.0)? I don't think so.

In order to find out hugo versions used out in the field, I started issue new thread inside our discussion forum.

Recommendation for 0.75.0 or later

I just found this issue in the example-site repo which explains the motivation behind this:

0.75.0 is the minimum version for the print feature to work so I'll update the docs.

However, print feature was amended by this commit( https://github.com/google/docsy/commit/2c411821dbd206821fb586f6ab75cae1302c1f99), so even versions below 0.75 should be fine right now.

deining

comment created time in a day

pull request commentgoogle/docsy

Ensure a smooth transition for existing docsy-as-submodule users #848

Some docsy code makes use of hugo.IsProduction (a feature that was added by gohugoio/hugo#6953). As far as I can tell, there can be only a single value for hugo.Environment, so setting it to module prevents projects from using production in production builds, etc. Does that make sense?

Yes, I see the point.

Unless we can find a way to allow hugo.IsProduction to be true while still using Docsy as a module, we won't be able to use the config directory approach.

I like the config directory approach, so I tried to make in work in another way: we now do have two config directories and we can use hugo's --configDir option to select one. That's how it is supposed to work:

Using docsy as git submodule

hugo serve --configDir configTheme

Using docsy as hugo module

hugo serve --configDir configModule

Empty default config directory at the beginning, the user has to give --configDir to get it up and running. After successful installation, the user may symlink config directory to one of both directories to make it the default way of running. Checks are failing now for this PR, this in on purpose. Not being able to start up the site in the default setting via hugo serve may sound harsh at first glance, but I see three advantages:

  • both installation types (submdule/module) are equivalent, no need to discuss about the recommended way of installation, and
  • the installation will get fail safe this way. With --environment flag approach, it you want to have module installation type and forget to add -e module at intial startup, I have seen weird things happen (pulling in bootstrap 5, ...). I'm afraid that users who haven't dealt with hugo modules already before can get easily lost here.
  • inside the empty ´configdir, we can put fileREADME.txt`, explaining how to make either submodules of modules the default. With multiple config files, that wouldn' t work out that well.

@chain, WDYT? If you like it, I will start testing my new approach.

deining

comment created time in a day

push eventdeining/docsy

zhaoyang

commit sha 19e0072b55bd42cdf4e9e58008147d604e3d31b4

fix: there is no need existing two zh*.toml file (#832) close #732 Co-authored-by: LisaFC <lcarey@google.com>

view details

Andreas Deininger

commit sha da85d627dcbefe02c974e6a23f7d623c53335c22

Ensure a smooth transition for existing docsy-as-submodule users #848

view details

Andreas Deininger

commit sha 199c4a5332b0bd1551c3dff94bb15f03fc5ac0a4

Work around a known bug in Go’s module management

view details

Andreas Deininger

commit sha 754cf6b446c914c576d99837a14cb0158e09a58d

Create separate config directories for each installation type (theme / module)

view details

push time in a day

push eventdeining/docsy

zhaoyang

commit sha 19e0072b55bd42cdf4e9e58008147d604e3d31b4

fix: there is no need existing two zh*.toml file (#832) close #732 Co-authored-by: LisaFC <lcarey@google.com>

view details

push time in a day

push eventdeining/docsy

Andreas Deininger

commit sha d83e16ba9e7144bbcad3ff84dfe523bb39555b6d

Create separate config directories for each installation type (theme / module)

view details

push time in a day

push eventgoogle/docsy

Andreas Deininger

commit sha d83e16ba9e7144bbcad3ff84dfe523bb39555b6d

Create separate config directories for each installation type (theme / module)

view details

push time in a day

issue openedgoogle/docsy

Inconsistent and vague docu on minimum required hugo version

I just skimmed through our sites, looking for minimum required hugo version. That's what I found:

README.md, section prerequisites: we recommend version 0.53 or later theme.toml: min_version = 0.53

  • Userguide:
    • section deployment: Specify HUGO_VERSION as the Key for the new variable, and 0.53 or later as its Value.
    • section Getting started, v 0.1.0: we recommend version 0.75.0 or later
    • section Getting started, HEAD: must be version 0.77.0 or later (this edit was done by me in the course of changing docsy to a module, this edit was a bit hasty and therefore premature, sorry).

I have two problems with that:

  • declared miniumum required version should be consistent all over the place
  • something like we recommend hugo version x.xx.x seem too vague to me. What meaning does that convey to the user? We don't really know by ourselves, so you may be able to keep your old, outdated version, good luck!

What was the reason of recommending 0.75.0 or later? Can anyone shed some light on this? Thanks.

created time in a day

pull request commentgoogle/docsy

Ensure a smooth transition for existing docsy-as-submodule users #848

This solution seems promising, but I'm concerned that it won't work for projects who want to use modules in a production environment.

Can you elaborate con your concerns a bit, please? What are you exactly concerned about? Why do you think that a multiple config approach might be more promising?

deining

comment created time in 2 days

push eventgoogle/docsy

Andreas Deininger

commit sha d9f398134b4bdb2a3d1ce8f71fbcad8085e90303

Work around a known bug in Go’s module management

view details

push time in 2 days

push eventdeining/docsy

Andreas Deininger

commit sha d9f398134b4bdb2a3d1ce8f71fbcad8085e90303

Work around a known bug in Go’s module management

view details

push time in 2 days

Pull request review commentCaiJimmy/stack-docs

Documentation on how to use theme as hugo module

 If you are using Git to manage your Hugo site, add this theme as a submodule. git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack ``` +## Route 2 (recommended): use theme as Hugo module++- Turn your new site into a Hugo module:+```bash+hugo mod init github.com/me/my-new-blog+```++- Declare the `hugo-theme-stack` module as a dependency of your site:+```bash+hugo mod get github.com/CaiJimmy/hugo-theme-stack+```++- Add the following lines at the end of your `config.yaml`:++```yaml+module:+  # uncomment line below for temporary local development of module+  # replacements: "github.com/CaiJimmy/hugo-theme-stack -> ../../hugo-theme-stack"+  hugoVersion:+    extended: true+    min: 0.78.0

I think this block (hugoVersion) isn't necessary for the users to include it.

You are right. I removed this block from the config file.

deining

comment created time in 2 days

more