{"id":18445675,"url":"https://github.com/voronenko/projectdocs","last_synced_at":"2025-04-08T00:31:41.266Z","repository":{"id":47220739,"uuid":"65403098","full_name":"Voronenko/ProjectDocs","owner":"Voronenko","description":"This is boilerplate for project documentation portal.  Example can be seen here","archived":false,"fork":false,"pushed_at":"2022-12-08T09:53:14.000Z","size":9250,"stargazers_count":4,"open_issues_count":6,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-23T03:07:26.891Z","etag":null,"topics":["blockdiag","documentation","plantuml","python3","sphinx-doc"],"latest_commit_sha":null,"homepage":"https://voronenko.github.io/ProjectDocs/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Voronenko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-10T17:33:53.000Z","updated_at":"2024-08-07T18:32:18.000Z","dependencies_parsed_at":"2023-01-25T09:30:30.088Z","dependency_job_id":null,"html_url":"https://github.com/Voronenko/ProjectDocs","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voronenko%2FProjectDocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voronenko%2FProjectDocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voronenko%2FProjectDocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voronenko%2FProjectDocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Voronenko","download_url":"https://codeload.github.com/Voronenko/ProjectDocs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247755341,"owners_count":20990616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockdiag","documentation","plantuml","python3","sphinx-doc"],"created_at":"2024-11-06T07:06:51.603Z","updated_at":"2025-04-08T00:31:39.411Z","avatar_url":"https://github.com/Voronenko.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Why documentation can’t be the project ?\n\n#### Introduction\n\nThis article, based on my experience, demonstrates approach of organizing\ndocumentation in your project aiming following:\n\n* Make easier s/w project transition to support\n* Get single entry point for updates and info\n* Get project documented from multiple angles\n* Get your stakeholders involved\n* Get your developers involved\n* Get your ops involved\n* Get your testers involved\n\n#### Background\n\nI am in software development for more than decade now. I used to work in a\ndifferent teams and on different projects, including the one, that was\ntransferred on support from other teams and even companies.\n\nOn of the biggest and most usual problems faced were lacking of project\ndocumentation. In number of situations it was cause of the longer time needed to\ntake ownership over project. This is not usually failure of the team, sometimes\ndocumentation is just not included into budget.\n\n![](https://cdn-images-1.medium.com/max/800/1*ubEVY-CALIVd645hllCXqA.jpeg)\n\nThat’s why I always tried to include portions of the knowledge for future\nsupport (even for myself in a few months or years)\n\nMost often we are working with subset of diagrams, which are called informally\n4+1 architectural view set, i.e.\n\n**Development view**: Component, Package\u003cbr\u003e **Logical view**: Activity, State,\nClass\u003cbr\u003e **Physical view**: deployment\u003cbr\u003e **Process**: Activity, BPMN\u003cbr\u003e\n**Scenarios**: Use Case\n\nIn a bigger projects, usually project manager decides what visualization\npackages are used depending on his experience. I used to draw diagrams in MS\nVisio, Edraw, yEd, Openoffice Draw, also number of online tools like Gliffy,\nLucida charts, draw.io etc.\n\nCommon issue I had — is constant feeling, that I would draw them much easier\nwith pencil and scan afterwards. On some more complex diagram set another\nquestion I had was also “Hey how did I spend my working day today” :) As\ndiagrams also need to be constantly updated as software evolves, it was\nsometimes hard to track differences in proprietary binary formats or even\nconstantly check diagrams differences online (like Gliffy, where versioning is\nsupported). On some projects we had google docs with number of diagram file\nversions uploaded. If project used Confluence — it was probably the best case of\never possible. On some projects we had just wiki provided by bitbucket …\n\nFor a quite long time I was looking for consistent approach, how to keep my\ndiagrams sources as simple as possible. Basically I had very basic set of\nrequirements:\n\n* to spend minutes to draft diagram\n* to be able to see history of changes in source control\n* ideally be able to combine diagram with code\n\nLet me share with you current state of my findings:\n\n*****\n\n### Tool #1: Plant UML\n\nSite: [http://www.plantuml.com/](http://www.plantuml.com/)\n\nDependencies: java, GraphViz package\n\nDiagrams supported: UML set \u0026 a bit more\n\nTool is able to draw full set of UML diagrams, which makes it almost ideal,\nalthough your sales person probably will not be happy from look. But for\npurposes of documentation they are perfect:\n\nBut what is great, is that diagrams sources are pure text:\n\nThis allows you to put them together with code, for example as a block comment\nto your module, easily track changes in a source control system, etc\n\nTool has number of integrations with variety of software:\n[http://plantuml.com/running](http://plantuml.com/running) from IDE, to wiki or\nconfluence.\n\nYou can try interactively how to draw diagrams now at\n[https://www.planttext.com/](https://www.planttext.com/) or view few pre-created\ndiagrams at [http://bit.ly/plantdiag](http://bit.ly/plantdiag)\n\n*****\n\n### Tool #2: Blockdiag\n\nSite: [http://www.blockdiag.com/](http://www.blockdiag.com/)\n\nDependencies: python 2+\u003cbr\u003e Diagrams supported: blocks, sequences, activity,\nnetwork, rack, packet structure.\n\nActivity diagram, for example, looks a way better than one generated by plantUML\n\nCompared to PlantUML diagrams look better, but cons are that number of options\nis much lower. From other hand, there are some specific kind of diagrams, like\npacket structure, rack or just graphs — that make this tool ideal.\n\n*****\n\n### Tool #3: Sphinx doc\n\nSite: [http://www.sphinx-doc.org/](http://www.sphinx-doc.org/)\u003cbr\u003e Dependencies:\npython 2+\n\nPros: universal, including your own custom code to build the pages\n\nCons: plugins matter\n\nPlantUML and Blockdiag are perfect tools, and can be used on their own, to\ngenerate diagram images that you insert into your wikis afterwards.\n\nBut if you are looking for a full cycle solution for your project documentation\n— take a look on Sphinx doc.\n\nThis is universal solution to be engine of project documentation for project of\nany size, and my compete with wiki, confluence, and similar tools\n\n**Output formats**: HTML (including Windows HTML Help), LaTeX (for printable PDF\nversions), ePub, Texinfo, manual pages, plain text\n\n**Extensive cross-references**: semantic markup and automatic links for\nfunctions, classes, citations, glossary terms and similar pieces of information\n\n**Hierarchical structure**: easy definition of a document tree, with automatic\nlinks to siblings, parents and children\n\n**Automatic indices**: general index as well as a language-specific module\nindices\n\n**Code handling**: automatic highlighting using the Pygments highlighter\u003cbr\u003e\nExtensions: automatic testing of code snippets, inclusion of docstrings from\nPython modules (API docs), and more\n\n**Contributed extensions**: more than 50 extensions contributed by users in a\nsecond repository; most of them installable from PyPI\n\nPer my humble opinion, pros are:\n\n* Well known, themable\n* Wide range of plugins and extensions\n* Your own custom page generators\n* Advanced rst syntax\n\nAt that moment I can’t skip cons you should take into consideration:\n\n* “ReadTheDocs” theme\n* You need carefully select plugins\n* Development efforts at the start\n* Confusion on Markdown — if you use markdown each day, switching between rst and\nmarkdown will be a pane\n\nWhen I say, that “ReadTheDocs” theme is a cons — I mean, that probably the only\nexisting fully adapted theme for documentation is the one you saw hundred of\ntimes:\n\n*****\n\n### Project Docs bootstrap boilerplate\n\nAs a result of experimenting I came with solution based on tools demonstrated\nabove. The demo of the deployed artifact probably tells more than a few\nparagraphs:\n[http://labs.voronenko.info/ProjectDocs/](http://labs.voronenko.info/Project\n\n\n### Known issues:\n\n#### \"BlockDiag not found\"\n\nMost likely you are hitting:\n\n#### ubuntu, enable-jpeg requested but jpeg not found\n\nerror  ValueError: --enable-jpeg requested but jpeg not found, aborting\n\nsolution: `sudo apt-get install libjpeg-dev`\n\n\n#### MacOS\n\nzlib not found or libjpeg not found\n\nsolution: install dev packages using `xcode-select --install`  ,\ninstall jpeg-devel using `brew install libjpeg`\n\n#### Other clues\n\nTake a look on  https://github.com/Voronenko/projectdocs/blob/master/Dockerfile\nit has listed all binary packages required. Check you have all of them or alternatives.\n\n\n#### useful tools\n\nFormats convertor:  https://github.com/jgm/pandoc\n\nExample, to convert docs artifact:\n\n```sh\n\npandoc -s flow.docx -t rst -o product_flow.rst\n\n```\n\nConverting markdown artifact:\n\n```sh\n\npandoc --from=markdown --to=rst --output=README.rst README.md\n\n```\n\nPandaDoc online:  https://pandoc.org/try/\n\nOnline work pad for diagramming construction\nhttp://interactive.blockdiag.com/\n\nOnline work pad for UML diagrams construction\n\nhttp://plantuml.com/plantuml/uml/\n\nPlantUML learning pad with examples:\n\nhttp://www.planttext.com/planttext\n\n\nGenerate pgsql schema diagram with schemacrawler  http://sualeh.github.io/SchemaCrawler/ , example:\n\n```sh\n\nschemacrawler -server=postgresql -database=demo_test -user=postgres -password=postgres -infolevel=maximum -command=graph -outputformat=pdf -outputfile=database-diagram.pdf\n\n```\n\nGenerate pgsql schema diagram portal with schemaspy http://schemaspy.sourceforge.net/ , example:\n\n```sh\nschemaspy -t pgsql -db demo_test -host localhost -port 5432 -s public -u postgres -p postgres  -o output\n```\n\nIncorporate static code analysis into your project:\n\nDoxygen:\n\nhttps://github.com/michaeljones/breathe/tree/master\n\n\n## Building docs project\n\nYou have two options:\n\n- build locally with diagramming software installed separately\n- using dockerized image\n\n### local setup\n\nYou would need:\n\n- python 3 , pipenv, make\n- java 6-7-8 for plantUML\n\n\ndiagramming software\n\n- plantUML (http://plantuml.com/ , recipe https://github.com/Voronenko/ansible-developer_recipes/blob/master/tools/tasks_plantuml.yml)\n- blockdiag (http://blockdiag.com/en/ , installed via requirements.txt)\n\n\n### Running the local build\n\nAt this moment it is enough to run ./clean_build.sh\nResult will be produced out/html\n\n### Docker setup\n------------\n\nYou need to have docker installed. File ./docker_build.sh does similar task as clean_build.sh\n\n```sh\n\n#!/bin/bash\n\nDOCKER_UID=$(id -u)\n\nDOCKER_USER=$(whoami)\n\nRUNNING=$(docker inspect --format=\"{{ .State.Running }}\" projectdocs 2\u003e /dev/null)\n\nif [ $? -eq 1 ]; then\n  echo \"PROJECTDOCS CONTAINER DOES NOT EXIST - CREATE IT\"\n  docker create -it -v $PWD:/opt/sphinxproject --name projectdocs softasap/sphinx-projectdocs:latest bash\n  docker start projectdocs\n  echo projectdocs container created\nfi\n\nif [ \"$RUNNING\" == \"false\" ]; then\n  echo \"RUN PROJECTDOCS CONTAINER\"\n  docker start projectdocs\n  echo projectdocs container running\nfi\n\necho \"building docs\"\necho docker exec -it projectdocs bash -c \"export DOCKER_UID=${DOCKER_UID} \u0026\u0026 export DOCKER_USER=${DOCKER_USER} \u0026\u0026 /opt/sphinxproject/docker_entry_point.sh\"\ndocker exec -it projectdocs bash -c \"export DOCKER_UID=${DOCKER_UID} \u0026\u0026 export DOCKER_USER=${DOCKER_USER} \u0026\u0026 /opt/sphinxproject/docker_entry_point.sh\"\n\n```\n\n\n### Building epub project\n\nmake epub\n\n\nOptions for epub output\nThese options influence the epub output. As this builder derives from the HTML builder, the HTML options also apply where appropriate. The actual values for some of the options is not really important, they just have to be entered into the Dublin Core metadata.\n\nepub\\_basename\nThe basename for the epub file. It defaults to the project name.\n\nepub\\_theme\nThe HTML theme for the epub output. Since the default themes are not optimized for small screen space, using the same theme for HTML and epub output is usually not wise. This defaults to 'epub', a theme designed to save visual space.\n\nepub\\_title\nThe title of the document. It defaults to the html_title option but can be set independently for epub creation.\n\nepub\\_author\nThe author of the document. This is put in the Dublin Core metadata. The default value is 'unknown'.\n\nepub\\_language\nThe language of the document. This is put in the Dublin Core metadata. The default is the language option or 'en' if unset.\n\nepub\\_publisher\nThe publisher of the document. This is put in the Dublin Core metadata. You may use any sensible string, e.g. the project homepage. The default value is 'unknown'.\n\nepub\\_copyright\nThe copyright of the document. It defaults to the copyright option but can be set independently for epub creation.\n\nepub\\_identifier\nAn identifier for the document. This is put in the Dublin Core metadata. For published documents this is the ISBN number, but you can also use an alternative scheme, e.g. the project homepage. The default value is 'unknown'.\n\nepub\\_scheme\nThe publication scheme for the epub_identifier. This is put in the Dublin Core metadata. For published books the scheme is 'ISBN'. If you use the project homepage, 'URL' seems reasonable. The default value is 'unknown'.\n\nepub\\_uid\nA unique identifier for the document. This is put in the Dublin Core metadata. You may use a random string. The default value is 'unknown'.\n\nepub\\_cover\nThe cover page information. This is a tuple containing the filenames of the cover image and the html template. The rendered html cover page is inserted as the first item in the spine in content.opf. If the template filename is empty, no html cover page is created. No cover at all is created if the tuple is empty. Examples:\n\nepub\\_cover = ('_static/cover.png', 'epub-cover.html')\nepub\\_cover = ('_static/cover.png', '')\nepub\\_cover = ()\nThe default value is ().\n\nNew in version 1.1.\n\nepub\\_pre\\_files\nAdditional files that should be inserted before the text generated by Sphinx. It is a list of tuples containing the file name and the title. If the title is empty, no entry is added to toc.ncx. Example:\n\nepub\\_pre\\_files = [\n    ('index.html', 'Welcome'),\n]\nThe default value is [].\n\nepub\\_post\\_files\nAdditional files that should be inserted after the text generated by Sphinx. It is a list of tuples containing the file name and the title. This option can be used to add an appendix. If the title is empty, no entry is added to toc.ncx. The default value is [].\n\nepub\\_exclude\\_files\nA list of files that are generated/copied in the build directory but should not be included in the epub file. The default value is [].\n\nepub\\_tocdepth\nThe depth of the table of contents in the file toc.ncx. It should be an integer greater than zero. The default value is 3. Note: A deeply nested table of contents may be difficult to navigate.\n\nepub\\_tocdup\nThis flag determines if a toc entry is inserted again at the beginning of it’s nested toc listing. This allows easier navitation to the top of a chapter, but can be confusing because it mixes entries of differnet depth in one list. The default value is True.\n\n\n### Building kindle project\n\nmake mobi\n\nThe following configuration values can be used in `conf.py`. At a minimum, you must set the *mobi\\_theme* option:\n\nmobi\\_add\\_visible\\_links\nWhether or not to write out the full text of a hyperlink next to the link itself. If the document will be read on paper (or printed), it is a good idea to set this to `True`.\n\nDefault: `True`\n\nmobi\\_author\nThe author of the book.\n\n\u003e Default: `'unknown'`\n\nmobi\\_basename\nThe basename of the output file (the part of the filename that precedes `.mobi`)\n\n\u003e Default: The project name, with spaces removed.\n\nmobi\\_copyright\nThe copyright holder of the book.\n\n\u003e Default: The value of **copyright** in `conf.py`\n\nmobi\\_cover\nThe cover image for the book. This should be in `.jpg` format.\n\n\u003e Default: No cover image is used.\n\nmobi\\_exclude\\_files\n\n\u003e Default: no files are excluded.\n\nmobi\\_identifier\n\n\u003e Default: `'unknown'`\n\nmobi\\_language\n\n\u003e Default: The value of *language* in `conf.py`, or `'en'` if *language* is not set.\n\nmobi\\_post\\_files\n\n\u003e Default: no post files are used.\n\nmobi\\_pre\\_files\n\n\u003e Default: no pre files are used.\n\nmobi\\_publisher\nThe publisher name for the book.\n\n\u003e Default: `'unknown'`\n\nmobi\\_scheme\n\n\u003e Default: `'unknown'`\n\nmobi\\_theme\n*Required*. The mobi theme-file to use. If you don’t have a theme of your own, use the `epub` theme:\n\n    mobi_theme = 'epub'\n\nmobi\\_title\n\n\u003e Default: The value of *html\\_title* in `conf.py`.\n\nmobi\\_tocdepth\n\n\u003e Default: `3`.\n\nmobi\\_tocdup\n\n\u003e Default: `True`\n\nmobi\\_uid\n\n\u003e Default: `'unknown'`\n\n\n\n# Additional resources\n\n\nhttps://github.com/yoloseem/awesome-sphinxdoc\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoronenko%2Fprojectdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoronenko%2Fprojectdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoronenko%2Fprojectdocs/lists"}