search

diaspora / diaspora_federation

A library that provides functionalities needed for the diaspora* federation protocol.
GNU Affero General Public License v3.0
100 stars 29 forks source link

Confusion with documentation folder names #66

Open cmrd-senya opened 7 years ago

cmrd-senya commented 7 years ago

Currently diaspora_federation has two documentation sets in it: API reference documentation and protocol documentation. API reference documentation is generated with yardoc and placed in /doc folder. Protocol documentation is rendered via jekyll and is placed under /docs folder. The folder names doc and docs make some confusion. I always forget which one is which and have to ls the folder to get it. Maybe we should change doc to api_doc or api_reference and docs to protocol_doc or protocol_documentation?

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/45663196-confusion-with-documentation-folder-names?utm_campaign=plugin&utm_content=tracker%2F18074852&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F18074852&utm_medium=issues&utm_source=github).
SuperTux88 commented 7 years ago

The /docs folder is fix, because GitHub pages can only use this folder, see here.

But feel free to change the output folder for yardoc. This documentation is published here and I hope they don't depend on our .yardopts file, so I think we can change it there.

cmrd-senya commented 7 years ago

Maybe the following can work: folder /docs as a root for the documenation, and /docs/protocol and /docs/api as subfolders?

SuperTux88 commented 7 years ago

No. GitHub Pages is /docs folder or / folder ... nothing else.

spectacle b19107

cmrd-senya commented 7 years ago

If it was possible to tell jekyll to build site from a subfolder, then we could move it downwards to /docs/protocol. But I didn't find the way to do that. I'll check if it is possible to move the api reference to a separate folder.

SuperTux88 commented 7 years ago

I'll check if it is possible to move the api reference to a separate folder.

You can set --output-dir in .yardopts. I hope www.rubydoc.info doesn't have a problem with that, because I have no control over that.