New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: init mkdocs and move documentation from DSP-DOCS into DSP-APP repo (DSP-380) #379
Merged
Merged
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
f9d882f
docs: init mkdocs
kilchenmann ba47394
docs: move content from dsp-docs to docs folder
kilchenmann 6b39334
chore(gh-ci): test and publish documentation
kilchenmann e0992e5
chore(gh-ci): test docs deployment
kilchenmann 084abe4
chore(gh-ci): undo docs deploy test
kilchenmann 4440fc4
docs: update and add docs documentation
kilchenmann a2c2715
docs(contribution): add release notes
kilchenmann 434de12
docs(user-guide): clean up structure
kilchenmann File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,91 @@ | ||
# DSP-APP Documentation | ||
|
||
This is the DSP-APP documentation, based on [MkDocs](https://www.mkdocs.org) and published | ||
under [http://dasch-swiss.github.io/dsp-app](http://dasch-swiss.github.io/dsp-app). | ||
|
||
## Contribute | ||
|
||
If you would like to add your own contributions to the docs, please read the following information regarding the file structure to ensure you follow the same structure. | ||
|
||
### File structure | ||
|
||
The documentation consists of three main topics with subordinate themes: | ||
|
||
1. **index** contains all information about the DSP-APP | ||
1. **how-to-use** contains all about the usage of the DSP-APP modules | ||
- Getting Started = All about the installation and init configuration | ||
- Core = Documentation for the core module content | ||
- Viewer = Documentation for the viewer module content | ||
- Search = Documentation for the search module content | ||
- Action = Documentation for the action module content | ||
1. **how-to-contribute** contains all information for people who wants to contribute to DSP-APP | ||
- Contribution = How to contribute incl. link to the general DSP contribution guidelines (<https://docs.dasch.swiss/developers/dsp/contribution/>) | ||
- Design Documentation = Structure conventions | ||
- Docs Documentation = This document | ||
- Release Notes = Contains the CHANGELOG file of DSP-APP | ||
|
||
Images like screenshots and so on have to be stored in `assets/images`. | ||
|
||
The `mkdocs.yml` file is present in the top-level directory of the repo and the source files are in the `docs/` folder. | ||
|
||
Plugins have to be defined in `requirements.txt` and in the github actions workflow `deploy-docs` step under `EXTRA_PACKAGES`. | ||
|
||
## Getting Started | ||
|
||
To run the documentation locally you'll need [Python](https://www.python.org/) installed, as well as the Python package manager [pip](http://pip.readthedocs.io/en/stable/installing/). You can check if you already have these installed by running the following commands from the command line: | ||
|
||
```shell | ||
$ python --version | ||
Python 3.8.2 | ||
$ pip --version | ||
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8) | ||
``` | ||
|
||
MkDocs supports Python versions 3.5, 3.6, 3.7, 3.8, and pypy3. | ||
|
||
### Installing dependencies | ||
|
||
Install the required packages by running the following command: | ||
|
||
```shell | ||
make docs-install-requirements | ||
``` | ||
|
||
### Running the documentation locally | ||
|
||
MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the `mkdocs.yml` (repository's root folder) configuration file, and then start the server by running the following command: | ||
|
||
```shell | ||
$ make docs-serve | ||
INFO - Building documentation... | ||
INFO - Cleaning site directory | ||
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 | ||
[I 160402 15:50:43 handlers:58] Start watching changes | ||
[I 160402 15:50:43 handlers:60] Start detecting changes | ||
``` | ||
|
||
Open up <http://127.0.0.1:8000/> in your browser, and you'll see the documentation start page being. | ||
|
||
In case you need to clean the project directory, run: | ||
|
||
```shell | ||
make docs-clean | ||
``` | ||
|
||
To get some help about the `make` commands, run: | ||
|
||
```shell | ||
make help | ||
``` | ||
|
||
### Building the documentation | ||
|
||
To build the documentation, run: | ||
|
||
```shell | ||
make docs-build | ||
``` | ||
|
||
### Deploying github page | ||
|
||
On each release of DSP-APP, a github action script will build and deploy the documentation on [dasch-swiss.github.io/dsp-app](https://dasch-swiss.github.io/dsp-app). Behind the scenes, MkDocs builds the documentation and uses the [mkdocs-deploy-gh-pages](https://github.com/marketplace/actions/deploy-mkdocs) actions script to deploy them to the gh-pages. That's it! |
Binary file not shown.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"contains all about" > weird to me
do you mean "all the information about..."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes it's weird... I'll fix it
This section is anyway complete nonsense. I copied from DSP-UI but didn't update the structure 🙈
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
but as you said, "the big refactoring will be part of another PR." So you could aadd this point to the other PR.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sure... but the content came from DSP-UI documentation and has to be updated for DSP-APP. DSP-APP documentation has another structure than DSP-UI
resolved it in 4440fc4