search

useblocks / sphinx-bazel

Sphinx extension to read bazel files
http://sphinx-bazel.readthedocs.io/en/latest/
Apache License 2.0
11 stars 4 forks source link

Empty BUILD file problems #7

Closed danwos closed 5 years ago

danwos commented 5 years ago

Bazel BUILD file can be empty, which in the current implementation causes obfuscation of the documentation structure

danwos commented 5 years ago

Can not reproduce this. Added test case in 0bb6ced. It it looks all good, if packages "main" has an empty BUILD file.

danwos commented 5 years ago

Can you provide a scenario, where it fails?

apekter commented 5 years ago

Bazel BUILD file can be empty, which in the current implementation causes obfuscation of the documentation structure

At the moment if the BUILD file is empty the package is not properly documented as mentioned in https://github.com/useblocks/sphinx-bazel/issues/8.

Overall the problem is a bit more complicated. With the current approach the sphinx-bazel is generating the documentation based on the file structure of the project. From bazel aspect the right approach would be to document the project from the standpoint of a target instead.

The sphinx-bazel suppose to generate similar if not exactly the same output as bazel stardoc rules do and have an extended functionality on top of this. Bazel stardoc follows the dependency graph of the build itself to generate the results. This gives a clear understanding of usage and the structure of the build, which is not necessarily reflected in the folder structure of the project itself.

danwos commented 5 years ago

Overall the problem is a bit more complicated. With the current approach the sphinx-bazel is generating the documentation based on the file structure of the project. From bazel aspect the right approach would be to document the project from the standpoint of a target instead.

I somehow disagree. Yes, sphinx-bazel is creating the documentation based on file structure, with the WORKSPACE as root element. However, choosing the WORKSPACE as root-element is optional. It could also be a package or a single target.

stardoc documents single targets only on a single page. You (will) get the same information with sphinx-bazel by just using autobazel-target: //package:target (Attributes implementation is on the way)

Bazel stardoc follows the dependency graph of the build itself to generate the results.

To be honest I haven't seen any example with documented dependencies of a rule yet. For me the output of stardoc for a single target has information coming from the related .bzl-files only. I don't know if the list of documented rules are based on the dependency graph of a current build. Maybe that's the case. But such a feature is currently not possible with sphinx-bazel, as bazel itself or its execution shall not be a requirement for documentation generation. Therefor we focus currently on file structure.

The sphinx-bazel suppose to generate similar if not exactly the same output as bazel stardoc rules do and have an extended functionality on top of this

Yes and no :) Yes sphinx-bazel shall provide the same kind of information. No it shall not generate the same output. E.g. a single file with defined layout for each rule. But this shall be possible, if defined by the user :)

The clustering of information is a task for the user. He/She can decide if several targets shall be part of a single page, get their own page or are even embedded into a longer, manual written documentation. That's totally up by the user.

However, a general API-documentation shall be possible and doable with 1-2 commands. But I see no need to focus hardly on the layout of stardoc for this.

This gives a clear understanding of usage and the structure of the build, which is not necessarily reflected in the folder structure of the project itself.

I totally agree that the files structure my not reflect a single build. But do you have any example/image for me, where I can see the structure of a single build? I know bazel commands to get this. But I haven't seen it in stardoc yet.

But overall, thanks for all the inputs. It really helps a lot! :+1:

apekter commented 5 years ago

The key thing here is that the bazel build revolves around the build targets. Invoking a target build gives the desired output therefore my opinion is that the documentation should reflect this.

Overall the problem is a bit more complicated. With the current approach the sphinx-bazel is generating the documentation based on the file structure of the project. From bazel aspect the right approach would be to document the project from the standpoint of a target instead.

I somehow disagree. Yes, sphinx-bazel is creating the documentation based on file structure, with the WORKSPACE as root element. However, choosing the WORKSPACE as root-element is optional. It could also be a package or a single target.

stardoc documents single targets only on a single page. You (will) get the same information with sphinx-bazel by just using autobazel-target: //package:target (Attributes implementation is on the way)

Once the attribute parsing is included this would be acceptable.

Bazel stardoc follows the dependency graph of the build itself to generate the results.

To be honest I haven't seen any example with documented dependencies of a rule yet. For me the output of stardoc for a single target has information coming from the related .bzl-files only. I don't know if the list of documented rules are based on the dependency graph of a current build. Maybe that's the case. But such a feature is currently not possible with sphinx-bazel, as bazel itself or its execution shall not be a requirement for documentation generation. Therefor we focus currently on file structure.

Usually the dependencies are loaded or referenced over labels. So that should be fairly simple to resolve. When mentioned the dependency graph I didn't necessarily mean running bazel query, but the sphinx-bazel must be able to parse the build structure and make sense of it.

The sphinx-bazel suppose to generate similar if not exactly the same output as bazel stardoc rules do and have an extended functionality on top of this

Yes and no :) Yes sphinx-bazel shall provide the same kind of information. No it shall not generate the same output. E.g. a single file with defined layout for each rule. But this shall be possible, if defined by the user :)

The clustering of information is a task for the user. He/She can decide if several targets shall be part of a single page, get their own page or are even embedded into a longer, manual written documentation. That's totally up by the user.

However, a general API-documentation shall be possible and doable with 1-2 commands. But I see no need to focus hardly on the layout of stardoc for this.

While saying "similar if not exactly the same output" I was referring to the indexed html pages content and not the output on a level of the single file. Additionally having a single page per bazel rule could be beneficial. (For big projects having everything in one page can cause problems).

This gives a clear understanding of usage and the structure of the build, which is not necessarily reflected in the folder structure of the project itself.

I totally agree that the files structure my not reflect a single build. But do you have any example/image for me, where I can see the structure of a single build? I know bazel commands to get this. But I haven't seen it in stardoc yet.

I did not say that stardoc does this at the moment but it is necessary for high quality documentation.

danwos commented 5 years ago

Okay, the overall problem of his issue got fixed and has a test case. So I close this issue.

Attribute documentation is also done. For the rest we may need some new issues and more specific content, how the final documentation result shall look like.