Create Doc Home Page

[jbogarthyde]

UPDATE 05/27/2024 (transfer issue from in-toto/docs, update issue description)

The landing page URL for the read-the-docs site currently hosts the auto-generated Python reference doc. To use Read the Docs as the site generator, expand and repurpose this URL as the new overall Doc home page, add user-doc build files in user-doc source directory, and modify the destination for the reference-doc build.
See Umbrella Doc Issue

• Add a source subdirectory to https://github.com/in-toto/docs github.com/in-toto/in-toto.io to contain the sources for web-based user documentation.
  • Expose subpage at in-toto.io/docs
  • Apply a Hugo theme, suited for usage documentation, to that subpage only.
• Add a new source file for the Documentation Home Page. The initial content is roadmap that describes and provides access to:
  • in-toto Technical Specification
  • Basic demo
  • Python reference implementation reference docs
• Add build files in the docs repo for the chosen static site generation tool to build the new doc home page.
• Change the destination for the reference doc build. It should go into a sub-section of the home page with the title "Python Reference Documentation"). The makefile and sources for the generated doc are in https://github.com/in-toto/in-toto/tree/develop/doc
• Add a link to the new Doc Home Page. Make it the first menu item in the Learn More menu on the project home page.
  • The link could go into the main menu bar, and likely replace "Get started", which currently points to similar content as described above

[jbogarthyde]

Please add the documentation label to this issue

[DarikshaAnsari]

Hey @JustinCappos,
As mentioned in the issue description we just have to utilize the current source code for the read-the-doc and modify it so that a dedicated documentation homepage can be served to the users?

If you think I am going in the right direction, It would be motivating if you can assign this issue to me.

[lukpueh]

Thanks for the initiative! There's a discussion about retiring the "docs" repo name, and rename it to "specification", which is more accurate for its current content. And as overall doc homepage, we could use in-toto.io:

in-toto/community#22

The reason for this proposal is that changing the purpose or complete content of a repo or website might confuse existing users and break other docs, which refer to these repos or sites.

[DarikshaAnsari]

@lukpueh No, I think we don't have to change complete content of this repo, rather we have to only add source subdirectory and make it visible on the first menu item in the Learn More menu on in-toto.io.

Also for the existing users the current read-the-doc contain Python reference implementation, which should go into a sub-section of the new home page with the title "Python Reference Documentation" , which will not confuse existing user.

Open to your assistance ,if i am wrong!!!

[lukpueh]

@lukpueh No, I think we don't have to change complete content of this repo, rather we have to only add source subdirectory and make it visible on the first menu item in the Learn More menu on in-toto.io.

Sure, we don't completely change the content, but we further broaden the scope of the repo. This makes sense if you think of the repo as what it's currently called, i.e. a general "docs" repo. But it makes less sense, if you think of it as what it actually is, i.e. the "spec" repo. IMO the specification is important enough to have its own dedicated repo, with an intuitive name, e.g. "specification".

So one idea is to just carve out the spec documents, dump them to a new repo, and keep this one the general docs repo.
I think that's fine too, the only downside is that there likely are many links to the spec in this repo out there, which would break. Now, if we rename the repo, people looking for the spec in this repo, will be forwarded to the new repo.

This would leave us without a "docs" repo for general docs. But I think in-toto.io could fill that spot.

Also for the existing users the current read-the-doc contain Python reference implementation, which should go into a sub-section of the new home page with the title "Python Reference Documentation" , which will not confuse existing user.

Same as above, I think moving things around like this will be more disruptive than beneficial.

[lukpueh]

Another reason for using in-toto.io for general docs is to bundle our efforts in one place. in-toto.io could already use more maintainers/contributors. If we have two places for general project-wide infos and docs, this situation will probably not get better.

[DarikshaAnsari]

but we already have one file in-toto-spec.md which already contain all the necessary specification of the in-toto which is currently reside in in-toto doc here, so if we make this repo as specification repo so there is a confusion between these two as we have two file/repo which describe the specification of in-toto

[lukpueh]

I think there's a misunderstanding. My proposal above is to rename github.com/in-toto/docs to github.com/in-toto/specification.

This means there no longer will be a github.com/in-toto/docs repo, but old links to files in that repo (e.g. in-toto-spec.md) still work, as they will automatically be redirected to the same file in github.com/in-toto/specification.

[DarikshaAnsari]

Yeah, I got your point now , we can use in-toto.io for general docs makes it easier for new users and rename this repo as specs repo for developers/contributor so that new users gets helpful information without sorting through technical specifications.

[lukpueh]

My preferred way of moving forward (independently of repo renames) is to host project-wide usage documentation on in-toto.io, e.g. under the "Get started" tab.

A first step could be to submit a similar issue as here against https://github.com/in-toto/in-toto.io/issues to sketch out structure and initial contents. @DarikshaAnsari, would you be interested?

Here are some reasons, why I think this is a good idea:

• in-toto.io already provides a static site generator for project-wide docs. We could save ourselves the effort to setup a new one.
• Given our resources, it does not seem feasible to maintain two places with project-wide docs.
• Project-wide docs should not include library reference docs of one specific implementation, but using RTD only makes sense for the in-toto Python implementation.
• Despite its name, this repo now is primarily a "spec" repo. Given all of above, it does not seem necessary to further broaden its scope.

[DarikshaAnsari]

@lukpueh Yes!! I am interested working on this.
Let me raise an issue here highlighting the following key aspects by referencing about the current issue #86:

1. Objective of raising the issue
2. Proposed Changes
3. Expected Outcome

I am much clear about the objective and expected outcome although regarding the proposed changes I will better need guidance regarding the exact content to be served as Project-wide docs.

We can have a dedicated discussion regarding the further enhancement or your reviews over the proposed changes in the issue I will raise against https://github.com/in-toto/in-toto.io/issues

[jbogarthyde]

I believe the easiest way to proceed is to create the docs home page as the landing page in-toto.io. This URI currently lands on the reference doc for Python Reference Implementation. That doc is logically part of "project-wide docs", so it should be included in the RTD project, but moved down to a subdir, instead of being the landing page.

On the home page, there should be a TOC for the "project-wide docs". The TOC should have a section for Implementation Reference Docs, with a link to the Python Reference Implementation reference docs (at their new location), along with links to the reference docs for other implementations (which might be external).

I hope this is clear.

[lukpueh]

I believe the easiest way to proceed is to create the docs home page as the landing page in-toto.io. This URI currently lands on the reference doc for Python Reference Implementation.

Did you mean in-toto.readthedocs.io? Because in-toto.io currently does not land on the reference doc for Python in-toto.

That doc is logically part of "project-wide docs", so it should be included in the RTD project, but moved down to a subdir, instead of being the landing page.

There has been an agreement in the in-toto community that the Python "reference" implementation should be considered as one of multiple in-toto implementations. That is why I suggested to keep the project-wide docs (in-toto.io) and Python in-toto docs (http://in-toto.readthedocs.io, we can change the name to python-in-toto.readthedocs.io) separate.

On the home page, there should be a TOC for the "project-wide docs". The TOC should have a section for Implementation Reference Docs, with a link to the Python Reference Implementation reference docs (at their new location), along with links to the reference docs for other implementations (which might be external).

Agreed! (except for the part about new location for Python in-toto)

I hope this is clear.

Not entirely. I'd appreciate a comment to my question in https://github.com/in-toto/docs/issues/85#issuecomment-2107148234, that is, whether there is a specific reason to not use in-toto.io for project-wide docs.

[jbogarthyde]

Thanks for the correction, Lukas -- yes, I did indeed mean that the doc home page should be http://in-toto.readthedocs.io/, with a prominent "Documentation" link on the in-toto home page, http://in-toto.io, and another link at the top of the Get Started menu.

The point of using http://in-toto.readthedocs.io/ as the doc landing page (rather than, say, in-toto.io/docs) is to keep RTD as the doc development tool, thus avoiding the overhead of starting with a new tool.

The project-wide doc home page can point to a Reference Docs section, with a link to the Python Reference Implementation reference docs. The sources for that doc can remain in Read-the-docs, but would need a new landing page - something like http://in-toto.readthedocs.io/referencedocs/python.

[lukpueh]

The point of using http://in-toto.readthedocs.io/ as the doc landing page (rather than, say, in-toto.io/docs) is to keep RTD as the doc development tool, thus avoiding the overhead of starting with a new tool.

Okay, thanks for clarifying! Given that we actually don't need to start a new tool, but can use the existing in-toto.io static site generator, plus the other arguments for using in-toto.io and against using in-toto.readthedocs.io for project-wide docs, I suggest we implement Judy's plan (#85) in in-toto.io. @DarikshaAnsari has kindly created an issue there: #24 (comment)

[lukpueh]

FYI: just transferred the issue from the in-toto/docs repo and updated the issue description as per the discussion

[DarikshaAnsari]

Now it looks good. I will proceed further with this issue.

[DarikshaAnsari]

@lukpueh

• Add a source subdirectory to https://github.com/in-toto/docs github.com/in-toto/in-toto.io to contain the sources for web-based user documentation.
• Expose subpage at in-toto.io/docs

I think this point is creating confusion about whether we have to add a source subdirectory or a docs subdirectory. Can you please make it clear?

[lukpueh]

• Add a source subdirectory to https://github.com/in-toto/docs github.com/in-toto/in-toto.io to contain the sources for web-based user documentation.

I suggest to create a directory /content/docs in this repo. It should be the root directory for all the new usage documentation mentioned in the related issues (except the ones that go into the in-toto/community repo).

• Expose subpage at in-toto.io/docs

Here I meant the web URL, where the usage documentation can be browsed, i.e. https://in-toto.io/docs.

I think this point is creating confusion about whether we have to add a source subdirectory or a docs subdirectory. Can you please make it clear?

[Ayush9026]

@lukpueh sir will also try to solve this issue.

[nate-double-u]

@Ayush9026, while I appreciate your enthusiasm and know there is a lot of work here, you've posted on many of the issues related to the in-toto documentation. I know you are applying for the LFX Mentorship program, which will primarily be based on this issue set, so I'd suggest letting the application process play out before starting any of this work.

Note: I don't make the candidate selections, and of course, we welcome contributions outside the mentorship program, but in this case, I'd recommend patience.

[chalin]

@lukpueh @JustinCappos - in terms of "User doc sub-issues" listed in #46, I'd propose that we take a step back. If you feel that the docs section will grow, I'd suggest switching the entire website over to Hugo + Docsy. Some of the top-velocity CNCF projects use this duo, including:

• https://github.com/open-telemetry/opentelemetry.io
• https://github.com/kubernetes/website
• https://github.com/grpc/grpc.io

And more.

@DarikshaAnsari could handle the switch. I can offer guidance. If you agree, I'd propose setting up a separate development branch so that @DarikshaAnsari (and I) can submit small incremental updates, and progressively work towards migrating the entire website, while at the same time have deploy previews for the branch. After that, addressing this issue will be trivial.

[JustinCappos]

I don't have any strong feelings either way. I support this unless @lukpueh objects.

[lukpueh]

@chalin, thanks for the links. I didn't know docsy, but it looks a lot like what Dariksha and I had discussed. :) If you can help set this up, that would be great!