1. Janusgraph-Dev
  2. Topics

[ANNOUNCEMENT] The documentation is updated

Jan Jansen <faro...@...>
 

I pushed yesterday my janusgraph master to be updated and had a github_token configured on travis ci. I removed the token from my travis ci.

With the PR, i opened to ensure the base repo, with branch protection, and janusgraph-bot, we should able to prevent these changes again.

Oleksandr Porunov <alexand...@...>
 

>> For consistency (and modernization), what do you think about converting the main site (janusgraph.org) to use the same design & theme?

I think this could be good but I don't see an easy solution for this. On the beginning Jan have developed a main page with the same style as documentation but it had the next drawbacks:
- The main page is in the same repository as documentation page
- The documentation don't have a separate domain (docs.janusgraph.org). Instead, the documentation and main page share the same domain (janusgraph.org).
- No good solution to handle temporary blocks (Like Upcoming Events).
- Hard to create custom buttons or place text in different styles.
- Hard to have separated sections (like Features sections, About section, first footer section)
- The style has navigation bars on the right and left side which isn't needed on the main page. I.e. with that bars the main page looks like documentation part and not as a home page.

I would suggest keep home page and documentation in separate repositories.

But changing the home page style to look like documentation style might have its pros.
To achieve this we should do the next steps:
1) Make the header (navigation bar) to be always fixed in height.
2) Work with color scheme to decide which colors should be used for all elements. 

The 1st task is easy but the 2nd task is hard to be achieved because each person has its own taste and it is hard to make everyone happy with the color scheme. The thing is that a main page is NOT a documentation. The main page has totally different structure and purpose. The main page has more sections with different colors, so we cannot just take same colors from documentation style because it isn't enough for main page. I already tried to make a color set to be something like in documentation but it was looking too bad. You can check the conversation here https://github.com/JanusGraph/janusgraph.org/pull/64 .

In short, I agree that it would be good to have the same style on the main page as in the documentation but for this we should either have a designer or someone who can work on the color scheme. After the color scheme is developed for the main page, we can easily update it on the main page in  `_config.yml`.

On Saturday, August 31, 2019 at 8:26:45 PM UTC+3, Misha Brukman wrote:
On Sat, Aug 31, 2019 at 5:22 AM Oleksandr Porunov <ale...@...> wrote:
Thanks to Jan Jansen the whole documentation is now updated to new modernized documentation.

The new documentation is launched on https://docs.janusgraph.org/ 

Thanks for working on this and great job! The new docs pages look excellent and modern. For consistency (and modernization), what do you think about converting the main site (janusgraph.org) to use the same design & theme?

On a separate note, looks like the `master` branch on https://github.com/janusgraph/docs.janusgraph.org was missing a CNAME file with the contents "docs.janusgraph.org", so it wasn't serving anything at https://docs.janusgraph.org; I added a CNAME file so now it's serving, but it's missing an index.html file so accessing the home page still returns a 404.

I'll add a simple index.html that redirects to /master/ to make sure that site has something for users when they look at the top-level page.

We're also missing docs for versions 0.1 and 0.4, and the URLs being v0.2 and v0.3 means that any old links pointing to /0.2/ or /0.3/ are now broken, so either we need to change the directory names to match, or we can add URL redirects.

Here we have an option: we can either symlink v0.x -> 0.x thus making "0.x" canonical location (as before), or we can link the other way, which makes the "v0.x" URLs canonical. Either way, we should do one or the other to ensure that the old links aren't broken.

Thoughts?

Misha
Oleksandr Porunov <alexand...@...>
 

I think there could be a security problem with the current documentation deployment scenario. I don't know why travis removed half of the files (which is why the documentation was broken) but I think that there could be a problem either in Travis configuration or GITHUB_TOKEN which is used by travis to deploy documentation.
We should configure travis so that:
1) It executed deploy ONLY for merged commits into the main repository. It should not execute deploy step for commits in PRs or other forked repository.
2) Even if someone tries to execute deploy in his forked repository he should not be able to force Travis to push docs into docs.janusgraph.org repository.

I think that we should investigate it ASAP. 

On Saturday, August 31, 2019 at 8:26:45 PM UTC+3, Misha Brukman wrote:
On Sat, Aug 31, 2019 at 5:22 AM Oleksandr Porunov <ale...@...> wrote:
Thanks to Jan Jansen the whole documentation is now updated to new modernized documentation.

The new documentation is launched on https://docs.janusgraph.org/ 

Thanks for working on this and great job! The new docs pages look excellent and modern. For consistency (and modernization), what do you think about converting the main site (janusgraph.org) to use the same design & theme?

On a separate note, looks like the `master` branch on https://github.com/janusgraph/docs.janusgraph.org was missing a CNAME file with the contents "docs.janusgraph.org", so it wasn't serving anything at https://docs.janusgraph.org; I added a CNAME file so now it's serving, but it's missing an index.html file so accessing the home page still returns a 404.

I'll add a simple index.html that redirects to /master/ to make sure that site has something for users when they look at the top-level page.

We're also missing docs for versions 0.1 and 0.4, and the URLs being v0.2 and v0.3 means that any old links pointing to /0.2/ or /0.3/ are now broken, so either we need to change the directory names to match, or we can add URL redirects.

Here we have an option: we can either symlink v0.x -> 0.x thus making "0.x" canonical location (as before), or we can link the other way, which makes the "v0.x" URLs canonical. Either way, we should do one or the other to ensure that the old links aren't broken.

Thoughts?

Misha
Misha Brukman <mbru...@...>
 

On Sat, Aug 31, 2019 at 5:22 AM Oleksandr Porunov <alexand...@...> wrote:
Thanks to Jan Jansen the whole documentation is now updated to new modernized documentation.

The new documentation is launched on https://docs.janusgraph.org/ 

Thanks for working on this and great job! The new docs pages look excellent and modern. For consistency (and modernization), what do you think about converting the main site (janusgraph.org) to use the same design & theme?

On a separate note, looks like the `master` branch on https://github.com/janusgraph/docs.janusgraph.org was missing a CNAME file with the contents "docs.janusgraph.org", so it wasn't serving anything at https://docs.janusgraph.org; I added a CNAME file so now it's serving, but it's missing an index.html file so accessing the home page still returns a 404.

I'll add a simple index.html that redirects to /master/ to make sure that site has something for users when they look at the top-level page.

We're also missing docs for versions 0.1 and 0.4, and the URLs being v0.2 and v0.3 means that any old links pointing to /0.2/ or /0.3/ are now broken, so either we need to change the directory names to match, or we can add URL redirects.

Here we have an option: we can either symlink v0.x -> 0.x thus making "0.x" canonical location (as before), or we can link the other way, which makes the "v0.x" URLs canonical. Either way, we should do one or the other to ensure that the old links aren't broken.

Thoughts?

Misha
Oleksandr Porunov <alexand...@...>
 

Thanks to Jan Jansen the whole documentation is now updated to new modernized documentation.

The new documentation is launched on https://docs.janusgraph.org/ 
The repository which serves gh-pages for new generated documentation is https://github.com/JanusGraph/docs.janusgraph.org
The gh-pages branch in the main repository was removed.

To launch old documentation on old-docs.janusgraph.org The Linux Foundation should add a DNS record for old-docs.janusgraph.org to point to GitHub IPs. After that we will be able to add a link to the old documentation in our new documentation.

Best regards,
Oleksandr Porunov

1 - 5 of 5