LisaFC
commented
4 years ago Thanks so much for this! It's always easier for people who aren't as familiar with the project as, say, me to spot the bits in the instructions that are less than clear....
Both the docsy repo and the docsy-example contain config.toml files. I'd have expected the two config files to be very similar, but the one in the docsy repo is almost empty. I'm guessing therefore that I should put any params needed for my feature into the docsy-example repo only.
Yes, the top-level Docsy repo has a config.toml for the theme - there are only a couple of things you can meaningfully put in a config at theme level in Hugo (I'll find the list, the Hugo people seem to have "helpfully" reorganized their docs again...) so that's why it's basically empty. Any params your feature uses need to be in the config for an actual site, so yes, docsy-example as that's the site repo that we ask users to copy/use its config as an example of all the supported params. You should also add them to the config for the Docsy user guide, just because people also copy that and/or depending on your feature you may need/be able to demo it in it.
I've figured out that I should add usage instructions to the guide in the docsy repo. It took me a while to figure this out, as I was at first confused by the similar URLs and similar look and feel for the two sets of docs (docsy.dev and example.docsy.dev). I think it'd be good to prompt contributors to add usage docs for their new features or update the existing docs for any changes they make, and to point contributors to the place where they can add the docs.
Yes, that's a good idea. The example project is basically there to copy and hence has pretty much every sort of page you might ever want, the user guide is the actual theme instructions and is a bit more minimal. We could definitely make "where to update the docs" clearer.
Also we could probably make the look and feel a little more different, though I also didn't want to move too far from the base theme look just because users are going to copy it and won't want heavy customization that they then have to update/remove.
Should I add the new partial layout for my feature into both the docsy repo and the docsy-example repo? At first, I assumed I should, because otherwise how can you test it? But then I ran into major problems with updating the Docsy submodule in the Docsy Example repo. Even after I figured out how to commit changes to the submodule (the answer is here) , I ran into build problems on Netlify (local worked fine) and had to revert the changes. So now I'm thinking I should add the new layout just to the docsy repo, not to docsy-example.
Your new layout should just go in the theme so it'll be available to all sites - docsy-example uses the theme as a submodule so there's no need to add it there again (and if you do, depending on where you put it, it'll either be treated as an override and/or confuse Git). If you want to test a new layout:
- Test locally: the easiest thing to do is to pull down the theme submodule recursively into a local copy of docsy-example and then stick it in your local copy of the theme there
- Test on Netlify: add the new layout as an override in a project site's layouts/ directory, you probably want to make a throwaway copy/deployment of your site to futz around with.
Should I add the new parameters for my feature into both the docsy repo and the docsy-example repo? At first it seemed like I should add the related params to the docsy-example repo and not to the docsy repo, because the config.toml at the root of the docsy repo has very little in it and points to the docsy-example repo for a list of all params. But later, I'm thinking maybe I should add my params into the config file for the userguide in the docsy repo, as well as in the config file in the docs-example repo.
Yes, add the params to both userguide and docsy-example configs - it's vital for the docsy-example one as it's the canonical params list, but as I said above you may want to add it to the user guide as well if you want to demo your layout in the docs.
chalin
I'm interested in contributing a feature to Docsy, but I'm confused by the various repositories: "Goldydocs" (I'm not sure exactly what that is, but I've seen it referenced in the Docsy docs), this repo (google/docsy), and the Docsy example repo.
I found the contributor's guide in the user docs after a bit of a search. I've raised PR https://github.com/google/docsy/pull/188 to add a link to the user doc from the contrib guide in the repo, to make it easier to find. I think it'd be good to clarify a few things in the contributor's guide.
I'm keeping a running commentary in this issue, to make it easier to update the contributor's guide at some point. I may find time to do it myself at some point, but if anyone else wants to pick this up, please do!
When adding a feature to Docsy, my main confusion was around these points:
Both the docsy repo and the docsy-example contain
config.tomlfiles. I'd have expected the two config files to be very similar, but the one in the docsy repo is almost empty. I'm guessing therefore that I should put any params needed for my feature into the docsy-example repo only.I've figured out that I should add usage instructions to the guide in the docsy repo. It took me a while to figure this out, as I was at first confused by the similar URLs and similar look and feel for the two sets of docs (docsy.dev and example.docsy.dev). I think it'd be good to prompt contributors to add usage docs for their new features or update the existing docs for any changes they make, and to point contributors to the place where they can add the docs.
Ah, now I see that example.docsy.dev has the title Goldydocs. I think this is a little confusing and we should change the title to something prosaic but straightforward like "Docsy Example Site". :)
Should I add the new partial layout for my feature into both the docsy repo and the docsy-example repo? At first, I assumed I should, because otherwise how can you test it? But then I ran into major problems with updating the Docsy submodule in the Docsy Example repo. Even after I figured out how to commit changes to the submodule (the answer is here) , I ran into build problems on Netlify (local worked fine) and had to revert the changes. So now I'm thinking I should add the new layout just to the docsy repo, not to docsy-example.
Should I add the new parameters for my feature into both the docsy repo and the docsy-example repo? At first it seemed like I should add the related params to the docsy-example repo and not to the docsy repo, because the config.toml at the root of the docsy repo has very little in it and points to the docsy-example repo for a list of all params. But later, I'm thinking maybe I should add my params into the config file for the userguide in the docsy repo, as well as in the config file in the docs-example repo.