Developer Guide: Move to separate site from main user guide #799
Conversation
devdocs/njk/common.njk
Outdated
| </div> | ||
| {% endif %} | ||
| <br> | ||
| {% endmacro %} |
There was a problem hiding this comment.
Duplication of this file set me thinking. Should we use two site.json files in the same location so that some files can be shared between the two sites? I think we already support deploying from a specific site.json file.
There was a problem hiding this comment.
Oops. Forgot about this. This common.njk file is not useful for developer docs, so I'll remove it in a bit.
For a more general case, I think we should either totally separate the two sites or not at all.
If we reuse files using 2 site.json as suggested, the original reasoning that brought us to having 2 separate sites would still hold: say we update a resource that both sites use. Then the changes will propagate to the developer docs immediately but not the user docs.
If we want to focus more on enforcing a common style/resource etc between the two sites, then maybe making it one might be cleaner.
There was a problem hiding this comment.
say we update a resource that both sites use. Then the changes will propagate to the developer docs immediately but not the user docs.
Isn't that the correct behavior? Published user docs should remain as before until it is updated again while the source code of the user docs should be updated immediately (which happens automatically because the file is shared).
There was a problem hiding this comment.
Oh opps. I was confused. I see where you're coming from now. I think there is some value in being able to reuse certain content. I can certainly see it being useful if we have custom themes or layouts for example.
It's definitely technically possible, and I would envision a file directory structure similar to:
/markbind/
├─ docs/
├─ devGuide/
├─ devGuide.json
├─ userGuide/
├─ userGuide.json
├─ _markbind/
├─ boilerplates/
├─ ...
├─ css/
├─ images/
├─ ...
├─ src/
It sounds good, but I stopped to think a little in terms of actual implementation.
-
We seem to want 2 separate (physically distinct) sites, but actually just want 1 unified site... I'm not sure which takes precedence.
If all that we require is a separate deployment process, does it make sense for us to do a nested sub_site instead? -
At least for MarkBind, I notice that our developer guides and user guides don't have too much in common. In fact, as we are on 2 separate sites, even the header navbar is different. From the userGuide, it may be incorrect (due to broken links) to refer to the devGuide as "../devdocs", rather it should be "https://markbind.org/devdocs".
This means that even though most resources are put together, they are usually used by only one site.
I would expect sister projects (eg teammates) to be rather similar. I don't think there will be a significant overlap in resource use - I can't think of significant overlaps other than boilerplates and footers. Maybe it might be cleaner to just duplicate these content instead?
There was a problem hiding this comment.
To take a step even further back to take stock:
-
Do we want multiple sites to be in the same repo? Yes. Reason: the whole code base can evolve as one.
-
Do we want the multiple sites to be able to share code between them? Ideally, yes. But this is not a big concern at the moment. May not be trivial to do either. We can postpone that to a future PR.
-
Can we use Netlify to preview multiple sites when a PR comes in? This needs to be looked into. Without it, we will not be able to preview DB PRs because currently Netlify is set to preview UG site only.
-
Can we set up Travis to auto-publish to a different repo? Yes, that's what is needed in this use case.
-
Can we set up Travis to publish multiple sites in one repo to respective multiple repos? Probably not needed for this PR but good to be able to do in general?
In summary, no need to worry about sharing code between multiple sites but let's figure out how to update/preview/auto-publish multiple sites from one code base, taking the current use case as an example.
As per [1], our dev docs should not be in the same folder as the user guide. This is because user guides are only updated when MarkBind is published, however dev docs are potentially updated every time someone makes a change. Let's create a separate site in /devdocs and move our Developer Guide there. This entails a separate site entirely complete with its own MarkBind files and site.json. In doing so, we also need to create a separate repository for travis to deploy to. These settings are reflected in devdocs/site.json. [1]: MarkBind#793 (comment)
|
Closing this PR because our course of action has diverged significantly from this PR. |
Please refer to #838 instead.
What is the purpose of this pull request? (put "X" next to an item, remove the rest)
• [X] Documentation update
Follow-up from #793
What is the rationale for this request?
As per this comment, our dev docs should not be in the same site as the
user guide. This is because user guides are only updated when
MarkBind is published, however dev docs are potentially updated
every time someone makes a change.
What changes did you make? (Give an overview)
Let's create a separate site in /devdocs and move our Developer
Guide there. This entails a separate site entirely complete with
its own MarkBind files and site.json.
In doing so, we also need to create a separate repository for
travis to deploy to. These settings are reflected in
devdocs/site.json.
Is there anything you'd like reviewers to focus on?
I'm not too sure how we do our netlify and travis magic. Please let me know if I'm doing my settings wrong - I don't want a Site Update v2 :P
Testing instructions:
I realise we can't use netlify to preview our dev docs build anymore? Since now we essentially have 2 sites... :O